8 The documentation on docs.ceph.com is generated from the reStructuredText
9 sources in ``/doc/`` in the Ceph git repository.
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.
15 All pull requests that modify user-facing functionality must
16 include corresponding updates to documentation: see
17 `Submitting Patches`_ for more detail.
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``
24 For more information about the Ceph documentation, see
25 :doc:`/start/documenting-ceph`.
30 C and C++ can be documented with Doxygen_, using the subset of Doxygen
31 markup supported by Breathe_.
33 .. _Doxygen: http://www.doxygen.nl/
34 .. _Breathe: https://github.com/michaeljones/breathe
36 The general format for function documentation is
43 * Detailed description when necessary
45 * preconditions, postconditions, warnings, bugs or other notes
48 * return value (if non-void)
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`.
56 To generate the doxygen documentation in HTML format use:
60 # cmake --build . --target doxygen
62 HTML output will be under: ``build-doc/doxygen/html``
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
73 You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
75 .. _Graphviz: http://graphviz.org/
76 .. _`Graphviz extension documentation`: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
86 Most of the time, you'll want to put the actual DOT source in a
87 separate file, like this::
89 .. graphviz:: myfile.dot
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
101 .. _Ditaa: http://ditaa.sourceforge.net/
105 +--------------+ /=----\
106 | hello, world |-->| hi! |
107 +--------------+ \-----/
113 If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
114 declarative language for drawing things, and includes:
116 - `block diagrams`_: boxes and arrows (automatic layout, as opposed to
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
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/
134 You can use Inkscape to generate scalable vector graphics.
135 https://inkscape.org/en/ for restructuredText documents.
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.
141 By committing the SVG file, others will be able to update the
142 SVG diagrams using Inkscape.
144 HTML5 will support SVG inline.
146 .. _`Submitting Patches`: https://github.com/ceph/ceph/blob/master/SubmittingPatches.rst