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.doxygen.nl/
  34 .. _Breathe: https://github.com/michaeljones/breathe
  35
  36 The general format for function documentation is
  37
  38 .. code-block:: c
  39
  40   /**
  41    * Short description
  42    *
  43    * Detailed description when necessary
  44    *
  45    * preconditons, postconditions, warnings, bugs or other notes
  46    *
  47    * parameter reference
  48    * return value (if non-void)
  49    */
  50
  51 This should be in the header where the function is declared, and
  52 functions should be grouped into logical categories. The `librados C
  53 API`_ provides a complete example. It is pulled into Sphinx by
  54 `librados.rst`_, which is rendered at :doc:`/rados/api/librados`.
  55
  56 To generate the doxygen documentation in HTML format use:
  57
  58 ::
  59
  60    # cmake --build . --target doxygen
  61
  62 HTML output will be under: ``build-doc/doxygen/html``
  63
  64 .. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h
  65 .. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst
  66
  67 Drawing diagrams
  68 ================
  69
  70 Graphviz
  71 --------
  72
  73 You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
  74
  75 .. _Graphviz: http://graphviz.org/
  76 .. _`Graphviz extension documentation`: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
  77
  78 .. graphviz::
  79
  80    digraph "example" {
  81      foo -> bar;
  82      bar -> baz;
  83      bar -> th
  84    }
  85
  86 Most of the time, you'll want to put the actual DOT source in a
  87 separate file, like this::
  88
  89   .. graphviz:: myfile.dot
  90
  91
  92 Ditaa
  93 -----
  94
  95 You can use Ditaa_:
  96
  97 .. _Ditaa: http://ditaa.sourceforge.net/
  98
  99 .. ditaa::
 100
 101    +--------------+   /=----\
 102    | hello, world |-->| hi! |
 103    +--------------+   \-----/
 104
 105
 106 Blockdiag
 107 ---------
 108
 109 If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
 110 declarative language for drawing things, and includes:
 111
 112 - `block diagrams`_: boxes and arrows (automatic layout, as opposed to
 113   Ditaa_)
 114 - `sequence diagrams`_: timelines and messages between them
 115 - `activity diagrams`_: subsystems and activities in them
 116 - `network diagrams`_: hosts, LANs, IP addresses etc (with `Cisco
 117   icons`_ if wanted)
 118
 119 .. _Blockdiag: http://blockdiag.com/en/
 120 .. _`Cisco icons`: https://pypi.org/project/blockdiagcontrib-cisco/
 121 .. _`block diagrams`: http://blockdiag.com/en/blockdiag/
 122 .. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html
 123 .. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html
 124 .. _`network diagrams`: http://blockdiag.com/en/nwdiag/
 125
 126
 127 Inkscape
 128 --------
 129
 130 You can use Inkscape to generate scalable vector graphics.
 131 https://inkscape.org/en/ for restructedText documents.
 132
 133 If you generate diagrams with Inkscape, you should
 134 commit both the Scalable Vector Graphics (SVG) file and export a
 135 Portable Network Graphic (PNG) file. Reference the PNG file.
 136
 137 By committing the SVG file, others will be able to update the
 138 SVG diagrams using Inkscape.
 139
 140 HTML5 will support SVG inline.
 141
 142 .. _`Submitting Patches`: https://github.com/ceph/ceph/blob/master/SubmittingPatches.rst