projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
1 | ================== |
| 2 | Documenting Ceph | |
| 3 | ================== | |
| 4 | ||
| 5 | Code Documentation | |
| 6 | ================== | |
| 7 | ||
| 8 | C and C++ can be documented with Doxygen_, using the subset of Doxygen | |
| 9 | markup supported by Breathe_. | |
| 10 | ||
| 11 | .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/ | |
| 12 | .. _Breathe: https://github.com/michaeljones/breathe | |
| 13 | ||
| 14 | The general format for function documentation is:: | |
| 15 | ||
| 16 | /** | |
| 17 | * Short description | |
| 18 | * | |
| 19 | * Detailed description when necessary | |
| 20 | * | |
| 21 | * preconditons, postconditions, warnings, bugs or other notes | |
| 22 | * | |
| 23 | * parameter reference | |
| 24 | * return value (if non-void) | |
| 25 | */ | |
| 26 | ||
| 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`. | |
| 31 | ||
| 32 | .. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h | |
| 31f18b77 | 33 | .. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst |
| 7c673cae FG |
34 | |
| 35 | Drawing diagrams | |
| 36 | ================ | |
| 37 | ||
| 38 | Graphviz | |
| 39 | -------- | |
| 40 | ||
| 41 | You can use Graphviz_, as explained in the `Graphviz extension documentation`_. | |
| 42 | ||
| 43 | .. _Graphviz: http://graphviz.org/ | |
| 44 | .. _`Graphviz extension documentation`: http://sphinx.pocoo.org/ext/graphviz.html | |
| 45 | ||
| 46 | .. graphviz:: | |
| 47 | ||
| 48 | digraph "example" { | |
| 49 | foo -> bar; | |
| 50 | bar -> baz; | |
| 51 | bar -> thud; | |
| 52 | } | |
| 53 | ||
| 54 | Most of the time, you'll want to put the actual DOT source in a | |
| 55 | separate file, like this:: | |
| 56 | ||
| 57 | .. graphviz:: myfile.dot | |
| 58 | ||
| 59 | ||
| 60 | Ditaa | |
| 61 | ----- | |
| 62 | ||
| 63 | You can use Ditaa_: | |
| 64 | ||
| 65 | .. _Ditaa: http://ditaa.sourceforge.net/ | |
| 66 | ||
| 67 | .. ditaa:: | |
| 68 | ||
| 69 | +--------------+ /=----\ | |
| 70 | | hello, world |-->| hi! | | |
| 71 | +--------------+ \-----/ | |
| 72 | ||
| 73 | ||
| 74 | Blockdiag | |
| 75 | --------- | |
| 76 | ||
| 77 | If a use arises, we can integrate Blockdiag_. It is a Graphviz-style | |
| 78 | declarative language for drawing things, and includes: | |
| 79 | ||
| 80 | - `block diagrams`_: boxes and arrows (automatic layout, as opposed to | |
| 81 | Ditaa_) | |
| 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 | |
| 85 | icons`_ if wanted) | |
| 86 | ||
| 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/ | |
| 93 | ||
| 94 | ||
| 95 | Inkscape | |
| 96 | -------- | |
| 97 | ||
| 98 | You can use Inkscape to generate scalable vector graphics. | |
| 99 | http://inkscape.org for restructedText documents. | |
| 100 | ||
| 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. | |
| 104 | ||
| 105 | By committing the SVG file, others will be able to update the | |
| 106 | SVG diagrams using Inkscape. | |
| 107 | ||
| 108 | HTML5 will support SVG inline. |