8 C and C++ can be documented with Doxygen_, using the subset of Doxygen
9 markup supported by Breathe_.
11 .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/
12 .. _Breathe: https://github.com/michaeljones/breathe
14 The general format for function documentation is::
19 * Detailed description when necessary
21 * preconditons, postconditions, warnings, bugs or other notes
24 * return value (if non-void)
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`.
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
41 You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
43 .. _Graphviz: http://graphviz.org/
44 .. _`Graphviz extension documentation`: http://sphinx.pocoo.org/ext/graphviz.html
54 Most of the time, you'll want to put the actual DOT source in a
55 separate file, like this::
57 .. graphviz:: myfile.dot
65 .. _Ditaa: http://ditaa.sourceforge.net/
69 +--------------+ /=----\
70 | hello, world |-->| hi! |
71 +--------------+ \-----/
77 If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
78 declarative language for drawing things, and includes:
80 - `block diagrams`_: boxes and arrows (automatic layout, as opposed to
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
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/
98 You can use Inkscape to generate scalable vector graphics.
99 http://inkscape.org for restructedText documents.
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.
105 By committing the SVG file, others will be able to update the
106 SVG diagrams using Inkscape.
108 HTML5 will support SVG inline.