src/ceph/doc/dev/documenting.rst

   1 ==================
   2  Documenting Ceph
   3 ==================
   4
   5 User documentation
   6 ==================
   7
   8 The documentation on docs.ceph.com is generated from the restructuredText
   9 sources in ``/doc/`` in the Ceph git repository.
  10
  11 Please make sure that your changes are written in a way that is intended
  12 for end users of the software, unless you are making additions in
  13 ``/doc/dev/``, which is the section for developers.
  14
  15 All pull requests that modify user-facing functionality must
  16 include corresponding updates to documentation: see
  17 `Submitting Patches`_ for more detail.
  18
  19 Check your .rst syntax is working as expected by using the "View"
  20 button in the github user interface when looking at a diff on
  21 an .rst file, or build the docs locally using the ``admin/build-doc``
  22 script.
  23
  24 For more information about the Ceph documentation, see
  25 :doc:`/start/documenting-ceph`.
  26
  27 Code Documentation
  28 ==================
  29
  30 C and C++ can be documented with Doxygen_, using the subset of Doxygen
  31 markup supported by Breathe_.
  32
  33 .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/
  34 .. _Breathe: https://github.com/michaeljones/breathe
  35
  36 The general format for function documentation is::
  37
  38   /**
  39    * Short description
  40    *
  41    * Detailed description when necessary
  42    *
  43    * preconditons, postconditions, warnings, bugs or other notes
  44    *
  45    * parameter reference
  46    * return value (if non-void)
  47    */
  48
  49 This should be in the header where the function is declared, and
  50 functions should be grouped into logical categories. The `librados C
  51 API`_ provides a complete example. It is pulled into Sphinx by
  52 `librados.rst`_, which is rendered at :doc:`/rados/api/librados`.
  53
  54 .. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h
  55 .. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst
  56
  57 Drawing diagrams
  58 ================
  59
  60 Graphviz
  61 --------
  62
  63 You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
  64
  65 .. _Graphviz: http://graphviz.org/
  66 .. _`Graphviz extension documentation`: http://sphinx.pocoo.org/ext/graphviz.html
  67
  68 .. graphviz::
  69
  70    digraph "example" {
  71      foo -> bar;
  72      bar -> baz;
  73      bar -> th
  74    }
  75
  76 Most of the time, you'll want to put the actual DOT source in a
  77 separate file, like this::
  78
  79   .. graphviz:: myfile.dot
  80
  81
  82 Ditaa
  83 -----
  84
  85 You can use Ditaa_:
  86
  87 .. _Ditaa: http://ditaa.sourceforge.net/
  88
  89 .. ditaa::
  90
  91    +--------------+   /=----\
  92    | hello, world |-->| hi! |
  93    +--------------+   \-----/
  94
  95
  96 Blockdiag
  97 ---------
  98
  99 If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
 100 declarative language for drawing things, and includes:
 101
 102 - `block diagrams`_: boxes and arrows (automatic layout, as opposed to
 103   Ditaa_)
 104 - `sequence diagrams`_: timelines and messages between them
 105 - `activity diagrams`_: subsystems and activities in them
 106 - `network diagrams`_: hosts, LANs, IP addresses etc (with `Cisco
 107   icons`_ if wanted)
 108
 109 .. _Blockdiag: http://blockdiag.com/
 110 .. _`Cisco icons`: http://pypi.python.org/pypi/blockdiagcontrib-cisco/
 111 .. _`block diagrams`: http://blockdiag.com/en/blockdiag/
 112 .. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html
 113 .. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html
 114 .. _`network diagrams`: http://blockdiag.com/en/nwdiag/
 115
 116
 117 Inkscape
 118 --------
 119
 120 You can use Inkscape to generate scalable vector graphics.
 121 http://inkscape.org for restructedText documents.
 122
 123 If you generate diagrams with Inkscape, you should
 124 commit both the Scalable Vector Graphics (SVG) file and export a
 125 Portable Network Graphic (PNG) file. Reference the PNG file.
 126
 127 By committing the SVG file, others will be able to update the
 128 SVG diagrams using Inkscape.
 129
 130 HTML5 will support SVG inline.
 131
 132 .. _Submitting Patches: /SubmittingPatches.rst