]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ================== |
2 | Documenting Ceph | |
3 | ================== | |
4 | ||
c07f9fc5 FG |
5 | User documentation |
6 | ================== | |
7 | ||
20effc67 | 8 | The documentation on docs.ceph.com is generated from the reStructuredText |
c07f9fc5 FG |
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 | ||
7c673cae FG |
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 | ||
11fdf7f2 | 33 | .. _Doxygen: http://www.doxygen.nl/ |
7c673cae FG |
34 | .. _Breathe: https://github.com/michaeljones/breathe |
35 | ||
20effc67 TL |
36 | The general format for function documentation is |
37 | ||
38 | .. code-block:: c | |
7c673cae FG |
39 | |
40 | /** | |
41 | * Short description | |
42 | * | |
43 | * Detailed description when necessary | |
44 | * | |
1e59de90 | 45 | * preconditions, postconditions, warnings, bugs or other notes |
7c673cae FG |
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 | ||
f67539c2 TL |
56 | To generate the doxygen documentation in HTML format use: |
57 | ||
58 | :: | |
59 | ||
20effc67 | 60 | # cmake --build . --target doxygen |
f67539c2 TL |
61 | |
62 | HTML output will be under: ``build-doc/doxygen/html`` | |
63 | ||
7c673cae | 64 | .. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h |
31f18b77 | 65 | .. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst |
7c673cae FG |
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/ | |
9f95a23c | 76 | .. _`Graphviz extension documentation`: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html |
7c673cae FG |
77 | |
78 | .. graphviz:: | |
79 | ||
80 | digraph "example" { | |
81 | foo -> bar; | |
82 | bar -> baz; | |
c07f9fc5 | 83 | bar -> th |
7c673cae FG |
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 | ||
39ae355f TL |
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. | |
7c673cae FG |
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 | ||
11fdf7f2 TL |
123 | .. _Blockdiag: http://blockdiag.com/en/ |
124 | .. _`Cisco icons`: https://pypi.org/project/blockdiagcontrib-cisco/ | |
7c673cae FG |
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. | |
1e59de90 | 135 | https://inkscape.org/en/ for restructuredText documents. |
7c673cae FG |
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. | |
c07f9fc5 | 145 | |
11fdf7f2 | 146 | .. _`Submitting Patches`: https://github.com/ceph/ceph/blob/master/SubmittingPatches.rst |