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    * preconditions, 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 See the `Dot User's Manual <https://www.graphviz.org/pdf/dotguide.pdf>`_ by
  92 Emden R. Gansner, Eleftherios Koutsofios, and Stephen North for examples of
  93 digraphs. This is especially useful if this is your first time encountering
  94 GraphViz.
  95
  96 Ditaa
  97 -----
  98
  99 You can use Ditaa_:
 100
 101 .. _Ditaa: http://ditaa.sourceforge.net/
 102
 103 .. ditaa::
 104
 105    +--------------+   /=----\
 106    | hello, world |-->| hi! |
 107    +--------------+   \-----/
 108
 109
 110 Blockdiag
 111 ---------
 112
 113 If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
 114 declarative language for drawing things, and includes:
 115
 116 - `block diagrams`_: boxes and arrows (automatic layout, as opposed to
 117   Ditaa_)
 118 - `sequence diagrams`_: timelines and messages between them
 119 - `activity diagrams`_: subsystems and activities in them
 120 - `network diagrams`_: hosts, LANs, IP addresses etc (with `Cisco
 121   icons`_ if wanted)
 122
 123 .. _Blockdiag: http://blockdiag.com/en/
 124 .. _`Cisco icons`: https://pypi.org/project/blockdiagcontrib-cisco/
 125 .. _`block diagrams`: http://blockdiag.com/en/blockdiag/
 126 .. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html
 127 .. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html
 128 .. _`network diagrams`: http://blockdiag.com/en/nwdiag/
 129
 130
 131 Inkscape
 132 --------
 133
 134 You can use Inkscape to generate scalable vector graphics.
 135 https://inkscape.org/en/ for restructuredText documents.
 136
 137 If you generate diagrams with Inkscape, you should
 138 commit both the Scalable Vector Graphics (SVG) file and export a
 139 Portable Network Graphic (PNG) file. Reference the PNG file.
 140
 141 By committing the SVG file, others will be able to update the
 142 SVG diagrams using Inkscape.
 143
 144 HTML5 will support SVG inline.
 145
 146 .. _`Submitting Patches`: https://github.com/ceph/ceph/blob/master/SubmittingPatches.rst