ceph/doc/dev/documenting.rst

   1 ==================
   2  Documenting Ceph
   3 ==================
   4
   5 Code Documentation
   6 ==================
   7
   8 C and C++ can be documented with Doxygen_, using the subset of Doxygen
   9 markup supported by Breathe_.
  10
  11 .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/
  12 .. _Breathe: https://github.com/michaeljones/breathe
  13
  14 The general format for function documentation is::
  15
  16   /**
  17    * Short description
  18    *
  19    * Detailed description when necessary
  20    *
  21    * preconditons, postconditions, warnings, bugs or other notes
  22    *
  23    * parameter reference
  24    * return value (if non-void)
  25    */
  26
  27 This should be in the header where the function is declared, and
  28 functions should be grouped into logical categories. The `librados C
  29 API`_ provides a complete example. It is pulled into Sphinx by
  30 `librados.rst`_, which is rendered at :doc:`/rados/api/librados`.
  31
  32 .. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h
  33 .. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst
  34
  35 Drawing diagrams
  36 ================
  37
  38 Graphviz
  39 --------
  40
  41 You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
  42
  43 .. _Graphviz: http://graphviz.org/
  44 .. _`Graphviz extension documentation`: http://sphinx.pocoo.org/ext/graphviz.html
  45
  46 .. graphviz::
  47
  48    digraph "example" {
  49      foo -> bar;
  50      bar -> baz;
  51      bar -> thud;
  52    }
  53
  54 Most of the time, you'll want to put the actual DOT source in a
  55 separate file, like this::
  56
  57   .. graphviz:: myfile.dot
  58
  59
  60 Ditaa
  61 -----
  62
  63 You can use Ditaa_:
  64
  65 .. _Ditaa: http://ditaa.sourceforge.net/
  66
  67 .. ditaa::
  68
  69    +--------------+   /=----\
  70    | hello, world |-->| hi! |
  71    +--------------+   \-----/
  72
  73
  74 Blockdiag
  75 ---------
  76
  77 If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
  78 declarative language for drawing things, and includes:
  79
  80 - `block diagrams`_: boxes and arrows (automatic layout, as opposed to
  81   Ditaa_)
  82 - `sequence diagrams`_: timelines and messages between them
  83 - `activity diagrams`_: subsystems and activities in them
  84 - `network diagrams`_: hosts, LANs, IP addresses etc (with `Cisco
  85   icons`_ if wanted)
  86
  87 .. _Blockdiag: http://blockdiag.com/
  88 .. _`Cisco icons`: http://pypi.python.org/pypi/blockdiagcontrib-cisco/
  89 .. _`block diagrams`: http://blockdiag.com/en/blockdiag/
  90 .. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html
  91 .. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html
  92 .. _`network diagrams`: http://blockdiag.com/en/nwdiag/
  93
  94
  95 Inkscape
  96 --------
  97
  98 You can use Inkscape to generate scalable vector graphics.
  99 http://inkscape.org for restructedText documents.
 100
 101 If you generate diagrams with Inkscape, you should
 102 commit both the Scalable Vector Graphics (SVG) file and export a
 103 Portable Network Graphic (PNG) file. Reference the PNG file.
 104
 105 By committing the SVG file, others will be able to update the
 106 SVG diagrams using Inkscape.
 107
 108 HTML5 will support SVG inline.