]>
Commit | Line | Data |
---|---|---|
1 | ================== | |
2 | Documenting Ceph | |
3 | ================== | |
4 | ||
5 | User documentation | |
6 | ================== | |
7 | ||
8 | The documentation on docs.ceph.com is generated from the restructuredText | |
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 | ||
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 | ||
33 | .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/ | |
34 | .. _Breathe: https://github.com/michaeljones/breathe | |
35 | ||
36 | The general format for function documentation is:: | |
37 | ||
38 | /** | |
39 | * Short description | |
40 | * | |
41 | * Detailed description when necessary | |
42 | * | |
43 | * preconditons, postconditions, warnings, bugs or other notes | |
44 | * | |
45 | * parameter reference | |
46 | * return value (if non-void) | |
47 | */ | |
48 | ||
49 | This should be in the header where the function is declared, and | |
50 | functions should be grouped into logical categories. The `librados C | |
51 | API`_ provides a complete example. It is pulled into Sphinx by | |
52 | `librados.rst`_, which is rendered at :doc:`/rados/api/librados`. | |
53 | ||
54 | .. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h | |
55 | .. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst | |
56 | ||
57 | Drawing diagrams | |
58 | ================ | |
59 | ||
60 | Graphviz | |
61 | -------- | |
62 | ||
63 | You can use Graphviz_, as explained in the `Graphviz extension documentation`_. | |
64 | ||
65 | .. _Graphviz: http://graphviz.org/ | |
66 | .. _`Graphviz extension documentation`: http://sphinx.pocoo.org/ext/graphviz.html | |
67 | ||
68 | .. graphviz:: | |
69 | ||
70 | digraph "example" { | |
71 | foo -> bar; | |
72 | bar -> baz; | |
73 | bar -> th | |
74 | } | |
75 | ||
76 | Most of the time, you'll want to put the actual DOT source in a | |
77 | separate file, like this:: | |
78 | ||
79 | .. graphviz:: myfile.dot | |
80 | ||
81 | ||
82 | Ditaa | |
83 | ----- | |
84 | ||
85 | You can use Ditaa_: | |
86 | ||
87 | .. _Ditaa: http://ditaa.sourceforge.net/ | |
88 | ||
89 | .. ditaa:: | |
90 | ||
91 | +--------------+ /=----\ | |
92 | | hello, world |-->| hi! | | |
93 | +--------------+ \-----/ | |
94 | ||
95 | ||
96 | Blockdiag | |
97 | --------- | |
98 | ||
99 | If a use arises, we can integrate Blockdiag_. It is a Graphviz-style | |
100 | declarative language for drawing things, and includes: | |
101 | ||
102 | - `block diagrams`_: boxes and arrows (automatic layout, as opposed to | |
103 | Ditaa_) | |
104 | - `sequence diagrams`_: timelines and messages between them | |
105 | - `activity diagrams`_: subsystems and activities in them | |
106 | - `network diagrams`_: hosts, LANs, IP addresses etc (with `Cisco | |
107 | icons`_ if wanted) | |
108 | ||
109 | .. _Blockdiag: http://blockdiag.com/ | |
110 | .. _`Cisco icons`: http://pypi.python.org/pypi/blockdiagcontrib-cisco/ | |
111 | .. _`block diagrams`: http://blockdiag.com/en/blockdiag/ | |
112 | .. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html | |
113 | .. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html | |
114 | .. _`network diagrams`: http://blockdiag.com/en/nwdiag/ | |
115 | ||
116 | ||
117 | Inkscape | |
118 | -------- | |
119 | ||
120 | You can use Inkscape to generate scalable vector graphics. | |
121 | http://inkscape.org for restructedText documents. | |
122 | ||
123 | If you generate diagrams with Inkscape, you should | |
124 | commit both the Scalable Vector Graphics (SVG) file and export a | |
125 | Portable Network Graphic (PNG) file. Reference the PNG file. | |
126 | ||
127 | By committing the SVG file, others will be able to update the | |
128 | SVG diagrams using Inkscape. | |
129 | ||
130 | HTML5 will support SVG inline. | |
131 | ||
132 | .. _Submitting Patches: /SubmittingPatches.rst |