Documenting Ceph

User documentation

The documentation on docs.ceph.com is generated from the restructuredTextsources in /doc/ in the Ceph git repository.

Please make sure that your changes are written in a way that is intendedfor end users of the software, unless you are making additions in/doc/dev/, which is the section for developers.

All pull requests that modify user-facing functionality mustinclude corresponding updates to documentation: seeSubmitting Patches for more detail.

Check your .rst syntax is working as expected by using the “View”button in the github user interface when looking at a diff onan .rst file, or build the docs locally using the admin/build-docscript.

For more information about the Ceph documentation, seeDocumenting Ceph.

Code Documentation

C and C++ can be documented with Doxygen, using the subset of Doxygenmarkup supported by Breathe.

The general format for function documentation is:

/**
 * Short description
 *
 * Detailed description when necessary
 *
 * preconditons, postconditions, warnings, bugs or other notes
 *
 * parameter reference
 * return value (if non-void)
 */

This should be in the header where the function is declared, andfunctions should be grouped into logical categories. The librados CAPI provides a complete example. It is pulled into Sphinx bylibrados.rst, which is rendered at Librados (C).

Drawing diagrams

Graphviz

You can use Graphviz, as explained in the Graphviz extension documentation.

Most of the time, you’ll want to put the actual DOT source in aseparate file, like this:

.. graphviz:: myfile.dot

Ditaa

You can use Ditaa:

Blockdiag

If a use arises, we can integrate Blockdiag. It is a Graphviz-styledeclarative language for drawing things, and includes:

• block diagrams: boxes and arrows (automatic layout, as opposed toDitaa)

• sequence diagrams: timelines and messages between them

• activity diagrams: subsystems and activities in them

• network diagrams: hosts, LANs, IP addresses etc (with Ciscoicons if wanted)

Inkscape

You can use Inkscape to generate scalable vector graphics.https://inkscape.org/en/ for restructedText documents.

If you generate diagrams with Inkscape, you shouldcommit both the Scalable Vector Graphics (SVG) file and export aPortable Network Graphic (PNG) file. Reference the PNG file.

By committing the SVG file, others will be able to update theSVG diagrams using Inkscape.

HTML5 will support SVG inline.