1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
==================
Documenting Ceph
==================
User documentation
==================
The documentation on docs.ceph.com is generated from the restructuredText
sources in ``/doc/`` in the Ceph git repository.
Please make sure that your changes are written in a way that is intended
for 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 must
include corresponding updates to documentation: see
`Submitting 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 on
an .rst file, or build the docs locally using the ``admin/build-doc``
script.
For more information about the Ceph documentation, see
:doc:`/start/documenting-ceph`.
Code Documentation
==================
C and C++ can be documented with Doxygen_, using the subset of Doxygen
markup supported by Breathe_.
.. _Doxygen: http://www.doxygen.nl/
.. _Breathe: https://github.com/michaeljones/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, and
functions should be grouped into logical categories. The `librados C
API`_ provides a complete example. It is pulled into Sphinx by
`librados.rst`_, which is rendered at :doc:`/rados/api/librados`.
To generate the doxygen documentation in HTML format use:
::
# make doxygen
HTML output will be under: ``build-doc/doxygen/html``
.. _`librados C API`: https://github.com/ceph/ceph/blob/master/src/include/rados/librados.h
.. _`librados.rst`: https://github.com/ceph/ceph/raw/master/doc/rados/api/librados.rst
Drawing diagrams
================
Graphviz
--------
You can use Graphviz_, as explained in the `Graphviz extension documentation`_.
.. _Graphviz: http://graphviz.org/
.. _`Graphviz extension documentation`: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
.. graphviz::
digraph "example" {
foo -> bar;
bar -> baz;
bar -> th
}
Most of the time, you'll want to put the actual DOT source in a
separate file, like this::
.. graphviz:: myfile.dot
See the `Dot User's Manual <https://www.graphviz.org/pdf/dotguide.pdf>`_ by
Emden R. Gansner, Eleftherios Koutsofios, and Stephen North for examples of
digraphs. This is especially useful if this is your first time encountering
GraphViz.
Ditaa
-----
You can use Ditaa_:
.. _Ditaa: http://ditaa.sourceforge.net/
.. ditaa::
+--------------+ /=----\
| hello, world |-->| hi! |
+--------------+ \-----/
Blockdiag
---------
If a use arises, we can integrate Blockdiag_. It is a Graphviz-style
declarative language for drawing things, and includes:
- `block diagrams`_: boxes and arrows (automatic layout, as opposed to
Ditaa_)
- `sequence diagrams`_: timelines and messages between them
- `activity diagrams`_: subsystems and activities in them
- `network diagrams`_: hosts, LANs, IP addresses etc (with `Cisco
icons`_ if wanted)
.. _Blockdiag: http://blockdiag.com/en/
.. _`Cisco icons`: https://pypi.org/project/blockdiagcontrib-cisco/
.. _`block diagrams`: http://blockdiag.com/en/blockdiag/
.. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html
.. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html
.. _`network diagrams`: http://blockdiag.com/en/nwdiag/
Inkscape
--------
You can use Inkscape to generate scalable vector graphics.
https://inkscape.org/en/ for restructedText documents.
If you generate diagrams with Inkscape, you should
commit both the Scalable Vector Graphics (SVG) file and export a
Portable Network Graphic (PNG) file. Reference the PNG file.
By committing the SVG file, others will be able to update the
SVG diagrams using Inkscape.
HTML5 will support SVG inline.
.. _`Submitting Patches`: https://github.com/ceph/ceph/blob/master/SubmittingPatches.rst
|
