]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ================== |
2 | Documenting Ceph | |
3 | ================== | |
4 | ||
20effc67 TL |
5 | You can help the Ceph project by contributing to the documentation. Even |
6 | small contributions help the Ceph project, such as fixing | |
7 | spelling errors or rewriting confusing instructions. | |
8 | ||
9 | The easiest way to suggest a correction to the documentation is to send an | |
10 | email to `ceph-users@ceph.io`. Include the string "ATTN: DOCS" or | |
11 | "Attention: Docs" or "Attention: Documentation" in the subject line. In | |
12 | the body of the email, include the text to be corrected (so that I can find | |
13 | it in the repo) and include your correction. | |
14 | ||
15 | Another way to suggest a documentation correction is to make a pull request. | |
16 | The instructions for making a pull request against the Ceph documentation are | |
17 | in the section :ref:`making_contributions`. | |
18 | ||
19 | If this is your first time making an improvement to the documentation or | |
20 | if you have noticed a small mistake (such as a spelling error or a typo), | |
21 | it will be easier to send an email than to make a pull request. You will | |
22 | be credited for the improvement unless you instruct Ceph Upstream | |
23 | Documentation not to credit you. | |
24 | ||
25 | Location of the Documentation in the Repository | |
26 | =============================================== | |
27 | ||
28 | The Ceph documentation source is in the ``ceph/doc`` directory of the Ceph | |
29 | repository. Python Sphinx renders the source into HTML and manpages. | |
30 | ||
31 | Viewing Old Ceph Documentation | |
32 | ============================== | |
33 | The https://docs.ceph.com link displays the ``master`` branch by default, but | |
34 | you can view the documentation for older versions of Ceph (e.g., ``mimic``) by | |
35 | replacing the version name in the url (e.g. ``pacific`` in | |
36 | `https://docs.ceph.com/en/pacific <https://docs.ceph.com/en/pacific>`_) with the | |
37 | branch name you prefer (e.g. ``mimic``, to create a URL that reads | |
38 | `https://docs.ceph.com/en/mimic/ <https://docs.ceph.com/en/mimic/>`_). | |
39 | ||
40 | .. _making_contributions: | |
7c673cae FG |
41 | |
42 | Making Contributions | |
43 | ==================== | |
44 | ||
20effc67 TL |
45 | Making a documentation contribution involves the same basic procedure as making |
46 | a code contribution, with one exception: you must build documentation source | |
47 | instead of compiling program source. This sequence (the sequence of building the documentation source) includes the following steps: | |
7c673cae FG |
48 | |
49 | #. `Get the Source`_ | |
50 | #. `Select a Branch`_ | |
51 | #. `Make a Change`_ | |
52 | #. `Build the Source`_ | |
53 | #. `Commit the Change`_ | |
54 | #. `Push the Change`_ | |
55 | #. `Make a Pull Request`_ | |
11fdf7f2 | 56 | #. `Notify Us`_ |
7c673cae FG |
57 | |
58 | Get the Source | |
59 | -------------- | |
60 | ||
61 | Ceph documentation lives in the Ceph repository right alongside the Ceph source | |
62 | code under the ``ceph/doc`` directory. For details on github and Ceph, | |
63 | see :ref:`Get Involved`. | |
64 | ||
65 | The most common way to make contributions is to use the `Fork and Pull`_ | |
66 | approach. You must: | |
67 | ||
f67539c2 TL |
68 | #. Install git locally. For Debian/Ubuntu, execute: |
69 | ||
70 | .. prompt:: bash $ | |
7c673cae FG |
71 | |
72 | sudo apt-get install git | |
73 | ||
f67539c2 TL |
74 | For Fedora, execute: |
75 | ||
76 | .. prompt:: bash $ | |
7c673cae FG |
77 | |
78 | sudo yum install git | |
79 | ||
f67539c2 TL |
80 | For CentOS/RHEL, execute: |
81 | ||
82 | .. prompt:: bash $ | |
7c673cae FG |
83 | |
84 | sudo yum install git | |
85 | ||
f67539c2 TL |
86 | #. Ensure your ``.gitconfig`` file has your name and email address. : |
87 | ||
88 | .. code-block:: ini | |
7c673cae FG |
89 | |
90 | [user] | |
91 | email = {your-email-address} | |
92 | name = {your-name} | |
93 | ||
f67539c2 TL |
94 | For example: |
95 | ||
96 | .. prompt:: bash $ | |
7c673cae FG |
97 | |
98 | git config --global user.name "John Doe" | |
99 | git config --global user.email johndoe@example.com | |
100 | ||
101 | ||
102 | #. Create a `github`_ account (if you don't have one). | |
103 | ||
104 | #. Fork the Ceph project. See https://github.com/ceph/ceph. | |
105 | ||
106 | #. Clone your fork of the Ceph project to your local host. | |
107 | ||
108 | ||
109 | Ceph organizes documentation into an information architecture primarily by its | |
110 | main components. | |
111 | ||
112 | - **Ceph Storage Cluster:** The Ceph Storage Cluster documentation resides | |
113 | under the ``doc/rados`` directory. | |
114 | ||
115 | - **Ceph Block Device:** The Ceph Block Device documentation resides under | |
116 | the ``doc/rbd`` directory. | |
117 | ||
118 | - **Ceph Object Storage:** The Ceph Object Storage documentation resides under | |
119 | the ``doc/radosgw`` directory. | |
120 | ||
9f95a23c | 121 | - **Ceph File System:** The Ceph File System documentation resides under the |
7c673cae FG |
122 | ``doc/cephfs`` directory. |
123 | ||
124 | - **Installation (Quick):** Quick start documentation resides under the | |
125 | ``doc/start`` directory. | |
126 | ||
127 | - **Installation (Manual):** Manual installation documentation resides under | |
128 | the ``doc/install`` directory. | |
129 | ||
130 | - **Manpage:** Manpage source resides under the ``doc/man`` directory. | |
131 | ||
132 | - **Developer:** Developer documentation resides under the ``doc/dev`` | |
133 | directory. | |
134 | ||
135 | - **Images:** If you include images such as JPEG or PNG files, you should | |
136 | store them under the ``doc/images`` directory. | |
137 | ||
138 | ||
139 | Select a Branch | |
140 | --------------- | |
141 | ||
142 | When you make small changes to the documentation, such as fixing typographical | |
143 | errors or clarifying explanations, use the ``master`` branch (default). You | |
144 | should also use the ``master`` branch when making contributions to features that | |
f67539c2 TL |
145 | are in the current release. ``master`` is the most commonly used branch. : |
146 | ||
147 | .. prompt:: bash $ | |
7c673cae FG |
148 | |
149 | git checkout master | |
150 | ||
151 | When you make changes to documentation that affect an upcoming release, use | |
f67539c2 TL |
152 | the ``next`` branch. ``next`` is the second most commonly used branch. : |
153 | ||
154 | .. prompt:: bash $ | |
7c673cae FG |
155 | |
156 | git checkout next | |
157 | ||
158 | When you are making substantial contributions such as new features that are not | |
159 | yet in the current release; if your contribution is related to an issue with a | |
160 | tracker ID; or, if you want to see your documentation rendered on the Ceph.com | |
161 | website before it gets merged into the ``master`` branch, you should create a | |
162 | branch. To distinguish branches that include only documentation updates, we | |
163 | prepend them with ``wip-doc`` by convention, following the form | |
164 | ``wip-doc-{your-branch-name}``. If the branch relates to an issue filed in | |
165 | http://tracker.ceph.com/issues, the branch name incorporates the issue number. | |
166 | For example, if a documentation branch is a fix for issue #4000, the branch name | |
167 | should be ``wip-doc-4000`` by convention and the relevant tracker URL will be | |
168 | http://tracker.ceph.com/issues/4000. | |
169 | ||
170 | .. note:: Please do not mingle documentation contributions and source code | |
9f95a23c TL |
171 | contributions in a single commit. When you keep documentation |
172 | commits separate from source code commits, it simplifies the review | |
173 | process. We highly recommend that any pull request that adds a feature or | |
174 | a configuration option, should also include a documentation commit, | |
175 | describing the relevant changes/options. | |
7c673cae FG |
176 | |
177 | Before you create your branch name, ensure that it doesn't already exist in the | |
f67539c2 TL |
178 | local or remote repository. : |
179 | ||
180 | .. prompt:: bash $ | |
7c673cae FG |
181 | |
182 | git branch -a | grep wip-doc-{your-branch-name} | |
183 | ||
f67539c2 TL |
184 | If it doesn't exist, create your branch: |
185 | ||
186 | .. prompt:: bash $ | |
7c673cae FG |
187 | |
188 | git checkout -b wip-doc-{your-branch-name} | |
189 | ||
190 | ||
191 | Make a Change | |
192 | ------------- | |
193 | ||
f67539c2 | 194 | Modifying a document involves opening a reStructuredText file, changing |
7c673cae FG |
195 | its contents, and saving the changes. See `Documentation Style Guide`_ for |
196 | details on syntax requirements. | |
197 | ||
f67539c2 TL |
198 | Adding a document involves creating a new reStructuredText file within the |
199 | ``doc`` directory tree with a ``*.rst`` | |
200 | extension. You must also include a reference to the document: a hyperlink | |
7c673cae FG |
201 | or a table of contents entry. The ``index.rst`` file of a top-level directory |
202 | usually contains a TOC, where you can add the new file name. All documents must | |
203 | have a title. See `Headings`_ for details. | |
204 | ||
205 | Your new document doesn't get tracked by ``git`` automatically. When you want | |
206 | to add the document to the repository, you must use ``git add | |
207 | {path-to-filename}``. For example, from the top level directory of the | |
208 | repository, adding an ``example.rst`` file to the ``rados`` subdirectory would | |
f67539c2 TL |
209 | look like this: |
210 | ||
211 | .. prompt:: bash $ | |
7c673cae FG |
212 | |
213 | git add doc/rados/example.rst | |
214 | ||
215 | Deleting a document involves removing it from the repository with ``git rm | |
f67539c2 TL |
216 | {path-to-filename}``. For example: |
217 | ||
218 | .. prompt:: bash $ | |
7c673cae FG |
219 | |
220 | git rm doc/rados/example.rst | |
221 | ||
222 | You must also remove any reference to a deleted document from other documents. | |
223 | ||
224 | ||
225 | Build the Source | |
226 | ---------------- | |
227 | ||
f67539c2 TL |
228 | To build the documentation, navigate to the ``ceph`` repository directory: |
229 | ||
230 | ||
231 | .. prompt:: bash $ | |
7c673cae FG |
232 | |
233 | cd ceph | |
234 | ||
f67539c2 TL |
235 | .. note:: |
236 | The directory that contains ``build-doc`` and ``serve-doc`` must be included | |
237 | in the ``PATH`` environment variable in order for these commands to work. | |
238 | ||
239 | ||
240 | To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute: | |
241 | ||
242 | .. prompt:: bash $ | |
7c673cae FG |
243 | |
244 | admin/build-doc | |
245 | ||
f67539c2 TL |
246 | To scan for the reachability of external links, execute: |
247 | ||
248 | .. prompt:: bash $ | |
7c673cae FG |
249 | |
250 | admin/build-doc linkcheck | |
251 | ||
f67539c2 TL |
252 | Executing ``admin/build-doc`` will create a ``build-doc`` directory under |
253 | ``ceph``. You may need to create a directory under ``ceph/build-doc`` for | |
254 | output of Javadoc files: | |
255 | ||
256 | .. prompt:: bash $ | |
7c673cae FG |
257 | |
258 | mkdir -p output/html/api/libcephfs-java/javadoc | |
259 | ||
260 | The build script ``build-doc`` will produce an output of errors and warnings. | |
f67539c2 TL |
261 | You MUST fix errors in documents you modified before committing a change, and |
262 | you SHOULD fix warnings that are related to syntax you modified. | |
7c673cae FG |
263 | |
264 | .. important:: You must validate ALL HYPERLINKS. If a hyperlink is broken, | |
265 | it automatically breaks the build! | |
266 | ||
11fdf7f2 | 267 | Once you build the documentation set, you may start an HTTP server at |
f67539c2 TL |
268 | ``http://localhost:8080/`` to view it: |
269 | ||
270 | .. prompt:: bash $ | |
7c673cae | 271 | |
11fdf7f2 | 272 | admin/serve-doc |
7c673cae | 273 | |
11fdf7f2 | 274 | You can also navigate to ``build-doc/output`` to inspect the built documents. |
7c673cae FG |
275 | There should be an ``html`` directory and a ``man`` directory containing |
276 | documentation in HTML and manpage formats respectively. | |
277 | ||
278 | Build the Source (First Time) | |
279 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
280 | ||
281 | Ceph uses Python Sphinx, which is generally distribution agnostic. The first | |
282 | time you build Ceph documentation, it will generate a doxygen XML tree, which | |
283 | is a bit time consuming. | |
284 | ||
285 | Python Sphinx does have some dependencies that vary across distributions. The | |
286 | first time you build the documentation, the script will notify you if you do not | |
287 | have the dependencies installed. To run Sphinx and build documentation successfully, | |
288 | the following packages are required: | |
289 | ||
290 | .. raw:: html | |
291 | ||
292 | <style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style> | |
293 | <table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3> | |
294 | ||
295 | - gcc | |
a4b75251 TL |
296 | - python3-dev |
297 | - python3-pip | |
298 | - python3-sphinx | |
20effc67 | 299 | - python3-venv |
7c673cae FG |
300 | - libxml2-dev |
301 | - libxslt1-dev | |
302 | - doxygen | |
303 | - graphviz | |
304 | - ant | |
305 | - ditaa | |
306 | ||
307 | .. raw:: html | |
308 | ||
309 | </td><td><h3>Fedora</h3> | |
310 | ||
311 | - gcc | |
312 | - python-devel | |
313 | - python-pip | |
7c673cae FG |
314 | - python-docutils |
315 | - python-jinja2 | |
316 | - python-pygments | |
317 | - python-sphinx | |
318 | - libxml2-devel | |
319 | - libxslt1-devel | |
320 | - doxygen | |
321 | - graphviz | |
322 | - ant | |
323 | - ditaa | |
324 | ||
325 | .. raw:: html | |
326 | ||
327 | </td><td><h3>CentOS/RHEL</h3> | |
328 | ||
329 | - gcc | |
330 | - python-devel | |
331 | - python-pip | |
7c673cae FG |
332 | - python-docutils |
333 | - python-jinja2 | |
334 | - python-pygments | |
335 | - python-sphinx | |
336 | - libxml2-dev | |
337 | - libxslt1-dev | |
338 | - doxygen | |
339 | - graphviz | |
340 | - ant | |
341 | ||
342 | .. raw:: html | |
343 | ||
344 | </td></tr></tbody></table> | |
345 | ||
346 | ||
c07f9fc5 | 347 | Install each dependency that is not installed on your host. For Debian/Ubuntu |
f67539c2 TL |
348 | distributions, execute the following: |
349 | ||
350 | .. prompt:: bash $ | |
7c673cae | 351 | |
a4b75251 | 352 | sudo apt-get install gcc python-dev python-pip libxml2-dev libxslt-dev doxygen graphviz ant ditaa |
7c673cae FG |
353 | sudo apt-get install python-sphinx |
354 | ||
f67539c2 TL |
355 | For Fedora distributions, execute the following: |
356 | ||
357 | .. prompt:: bash $ | |
7c673cae | 358 | |
a4b75251 | 359 | sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant |
7c673cae FG |
360 | sudo pip install html2text |
361 | sudo yum install python-jinja2 python-pygments python-docutils python-sphinx | |
362 | sudo yum install jericho-html ditaa | |
363 | ||
364 | For CentOS/RHEL distributions, it is recommended to have ``epel`` (Extra | |
365 | Packages for Enterprise Linux) repository as it provides some extra packages | |
366 | which are not available in the default repository. To install ``epel``, execute | |
f67539c2 TL |
367 | the following: |
368 | ||
369 | .. prompt:: bash $ | |
7c673cae FG |
370 | |
371 | sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm | |
372 | ||
f67539c2 TL |
373 | For CentOS/RHEL distributions, execute the following: |
374 | ||
375 | .. prompt:: bash $ | |
7c673cae | 376 | |
a4b75251 | 377 | sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant |
7c673cae FG |
378 | sudo pip install html2text |
379 | ||
f67539c2 TL |
380 | For CentOS/RHEL distributions, the remaining python packages are not available |
381 | in the default and ``epel`` repositories. So, use http://rpmfind.net/ to find | |
382 | the packages. Then, download them from a mirror and install them. For example: | |
383 | ||
384 | .. prompt:: bash $ | |
7c673cae FG |
385 | |
386 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm | |
387 | sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm | |
388 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm | |
389 | sudo yum install python-pygments-1.4-9.el7.noarch.rpm | |
390 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm | |
391 | sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm | |
392 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm | |
393 | sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm | |
394 | ||
c07f9fc5 | 395 | Ceph documentation makes extensive use of `ditaa`_, which is not presently built |
7c673cae FG |
396 | for CentOS/RHEL7. You must install ``ditaa`` if you are making changes to |
397 | ``ditaa`` diagrams so that you can verify that they render properly before you | |
398 | commit new or modified ``ditaa`` diagrams. You may retrieve compatible required | |
f67539c2 TL |
399 | packages for CentOS/RHEL distributions and install them manually. To run |
400 | ``ditaa`` on CentOS/RHEL7, following dependencies are required: | |
7c673cae FG |
401 | |
402 | - jericho-html | |
403 | - jai-imageio-core | |
404 | - batik | |
405 | ||
406 | Use http://rpmfind.net/ to find compatible ``ditaa`` and the dependencies. | |
f67539c2 TL |
407 | Then, download them from a mirror and install them. For example: |
408 | ||
409 | .. prompt:: bash $ | |
7c673cae FG |
410 | |
411 | wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm | |
412 | sudo yum install jericho-html-3.3-4.fc22.noarch.rpm | |
413 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm | |
414 | sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm | |
415 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm | |
416 | sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm | |
417 | wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm | |
418 | sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm | |
419 | ||
420 | Once you have installed all these packages, build the documentation by following | |
31f18b77 FG |
421 | the steps given in `Build the Source`_. |
422 | ||
7c673cae FG |
423 | |
424 | Commit the Change | |
425 | ----------------- | |
426 | ||
427 | Ceph documentation commits are simple, but follow a strict convention: | |
428 | ||
429 | - A commit SHOULD have 1 file per commit (it simplifies rollback). You MAY | |
430 | commit multiple files with related changes. Unrelated changes SHOULD NOT | |
431 | be put into the same commit. | |
432 | - A commit MUST have a comment. | |
433 | - A commit comment MUST be prepended with ``doc:``. (strict) | |
434 | - The comment summary MUST be one line only. (strict) | |
435 | - Additional comments MAY follow a blank line after the summary, | |
436 | but should be terse. | |
20effc67 | 437 | - A commit MAY include ``Fixes: https://tracker.ceph.com/issues/{bug number}``. |
7c673cae FG |
438 | - Commits MUST include ``Signed-off-by: Firstname Lastname <email>``. (strict) |
439 | ||
440 | .. tip:: Follow the foregoing convention particularly where it says | |
441 | ``(strict)`` or you will be asked to modify your commit to comply with | |
442 | this convention. | |
443 | ||
444 | The following is a common commit comment (preferred):: | |
445 | ||
446 | doc: Fixes a spelling error and a broken hyperlink. | |
447 | ||
448 | Signed-off-by: John Doe <john.doe@gmail.com> | |
449 | ||
450 | ||
451 | The following comment includes a reference to a bug. :: | |
452 | ||
453 | doc: Fixes a spelling error and a broken hyperlink. | |
454 | ||
20effc67 | 455 | Fixes: https://tracker.ceph.com/issues/1234 |
7c673cae FG |
456 | |
457 | Signed-off-by: John Doe <john.doe@gmail.com> | |
458 | ||
459 | ||
460 | The following comment includes a terse sentence following the comment summary. | |
461 | There is a carriage return between the summary line and the description:: | |
462 | ||
463 | doc: Added mon setting to monitor config reference | |
464 | ||
465 | Describes 'mon setting', which is a new setting added | |
466 | to config_opts.h. | |
467 | ||
468 | Signed-off-by: John Doe <john.doe@gmail.com> | |
469 | ||
470 | ||
f67539c2 TL |
471 | To commit changes, execute the following: |
472 | ||
473 | .. prompt:: bash $ | |
7c673cae FG |
474 | |
475 | git commit -a | |
476 | ||
477 | ||
478 | An easy way to manage your documentation commits is to use visual tools for | |
479 | ``git``. For example, ``gitk`` provides a graphical interface for viewing the | |
480 | repository history, and ``git-gui`` provides a graphical interface for viewing | |
481 | your uncommitted changes, staging them for commit, committing the changes and | |
482 | pushing them to your forked Ceph repository. | |
483 | ||
484 | ||
f67539c2 TL |
485 | For Debian/Ubuntu, execute: |
486 | ||
487 | .. prompt:: bash $ | |
7c673cae FG |
488 | |
489 | sudo apt-get install gitk git-gui | |
490 | ||
f67539c2 TL |
491 | For Fedora/CentOS/RHEL, execute: |
492 | ||
493 | .. prompt:: bash $ | |
7c673cae FG |
494 | |
495 | sudo yum install gitk git-gui | |
496 | ||
f67539c2 TL |
497 | Then, execute: |
498 | ||
499 | .. prompt:: bash $ | |
7c673cae FG |
500 | |
501 | cd {git-ceph-repo-path} | |
502 | gitk | |
503 | ||
504 | Finally, select **File->Start git gui** to activate the graphical user interface. | |
505 | ||
506 | ||
507 | Push the Change | |
508 | --------------- | |
509 | ||
510 | Once you have one or more commits, you must push them from the local copy of the | |
511 | repository to ``github``. A graphical tool like ``git-gui`` provides a user | |
f67539c2 TL |
512 | interface for pushing to the repository. If you created a branch previously: |
513 | ||
514 | .. prompt:: bash $ | |
7c673cae FG |
515 | |
516 | git push origin wip-doc-{your-branch-name} | |
517 | ||
f67539c2 TL |
518 | Otherwise: |
519 | ||
520 | .. prompt:: bash $ | |
7c673cae FG |
521 | |
522 | git push | |
523 | ||
524 | ||
525 | Make a Pull Request | |
526 | ------------------- | |
527 | ||
528 | As noted earlier, you can make documentation contributions using the `Fork and | |
529 | Pull`_ approach. | |
530 | ||
531 | ||
532 | ||
11fdf7f2 TL |
533 | Notify Us |
534 | --------- | |
7c673cae | 535 | |
20effc67 TL |
536 | In case The PR did not got a review within in a reasonable timeframe, please get in touch |
537 | with the corresponding component lead of the :ref:`clt`. | |
7c673cae FG |
538 | |
539 | Documentation Style Guide | |
540 | ========================= | |
541 | ||
542 | One objective of the Ceph documentation project is to ensure the readability of | |
20effc67 | 543 | the documentation in both native reStructuredText format and its rendered |
7c673cae FG |
544 | formats such as HTML. Navigate to your Ceph repository and view a document in |
545 | its native format. You may notice that it is generally as legible in a terminal | |
546 | as it is in its rendered HTML format. Additionally, you may also notice that | |
f67539c2 TL |
547 | diagrams in ``ditaa`` format also render reasonably well in text mode. : |
548 | ||
549 | .. prompt:: bash $ | |
7c673cae | 550 | |
11fdf7f2 | 551 | less doc/architecture.rst |
7c673cae FG |
552 | |
553 | Review the following style guides to maintain this consistency. | |
554 | ||
555 | ||
556 | Headings | |
557 | -------- | |
558 | ||
559 | #. **Document Titles:** Document titles use the ``=`` character overline and | |
560 | underline with a leading and trailing space on the title text line. | |
561 | See `Document Title`_ for details. | |
562 | ||
563 | #. **Section Titles:** Section tiles use the ``=`` character underline with no | |
564 | leading or trailing spaces for text. Two carriage returns should precede a | |
565 | section title (unless an inline reference precedes it). See `Sections`_ for | |
566 | details. | |
567 | ||
568 | #. **Subsection Titles:** Subsection titles use the ``_`` character underline | |
569 | with no leading or trailing spaces for text. Two carriage returns should | |
570 | precede a subsection title (unless an inline reference precedes it). | |
571 | ||
572 | ||
573 | Text Body | |
574 | --------- | |
575 | ||
576 | As a general rule, we prefer text to wrap at column 80 so that it is legible in | |
577 | a command line interface without leading or trailing white space. Where | |
578 | possible, we prefer to maintain this convention with text, lists, literal text | |
579 | (exceptions allowed), tables, and ``ditaa`` graphics. | |
580 | ||
581 | #. **Paragraphs**: Paragraphs have a leading and a trailing carriage return, | |
582 | and should be 80 characters wide or less so that the documentation can be | |
583 | read in native format in a command line terminal. | |
584 | ||
585 | #. **Literal Text:** To create an example of literal text (e.g., command line | |
586 | usage), terminate the preceding paragraph with ``::`` or enter a carriage | |
587 | return to create an empty line after the preceding paragraph; then, enter | |
588 | ``::`` on a separate line followed by another empty line. Then, begin the | |
589 | literal text with tab indentation (preferred) or space indentation of 3 | |
590 | characters. | |
591 | ||
592 | #. **Indented Text:** Indented text such as bullet points | |
593 | (e.g., ``- some text``) may span multiple lines. The text of subsequent | |
594 | lines should begin at the same character position as the text of the | |
595 | indented text (less numbers, bullets, etc.). | |
596 | ||
597 | Indented text may include literal text examples. Whereas, text indentation | |
598 | should be done with spaces, literal text examples should be indented with | |
599 | tabs. This convention enables you to add an additional indented paragraph | |
600 | following a literal example by leaving a blank line and beginning the | |
601 | subsequent paragraph with space indentation. | |
602 | ||
603 | #. **Numbered Lists:** Numbered lists should use autonumbering by starting | |
604 | a numbered indent with ``#.`` instead of the actual number so that | |
605 | numbered paragraphs can be repositioned without requiring manual | |
606 | renumbering. | |
607 | ||
608 | #. **Code Examples:** Ceph supports the use of the | |
609 | ``.. code-block::<language>`` role, so that you can add highlighting to | |
610 | source examples. This is preferred for source code. However, use of this | |
611 | tag will cause autonumbering to restart at 1 if it is used as an example | |
612 | within a numbered list. See `Showing code examples`_ for details. | |
613 | ||
614 | ||
615 | Paragraph Level Markup | |
616 | ---------------------- | |
617 | ||
618 | The Ceph project uses `paragraph level markup`_ to highlight points. | |
619 | ||
620 | #. **Tip:** Use the ``.. tip::`` directive to provide additional information | |
621 | that assists the reader or steers the reader away from trouble. | |
622 | ||
623 | #. **Note**: Use the ``.. note::`` directive to highlight an important point. | |
624 | ||
625 | #. **Important:** Use the ``.. important::`` directive to highlight important | |
626 | requirements or caveats (e.g., anything that could lead to data loss). Use | |
627 | this directive sparingly, because it renders in red. | |
628 | ||
629 | #. **Version Added:** Use the ``.. versionadded::`` directive for new features | |
630 | or configuration settings so that users know the minimum release for using | |
631 | a feature. | |
632 | ||
633 | #. **Version Changed:** Use the ``.. versionchanged::`` directive for changes | |
634 | in usage or configuration settings. | |
635 | ||
636 | #. **Deprecated:** Use the ``.. deprecated::`` directive when CLI usage, | |
637 | a feature or a configuration setting is no longer preferred or will be | |
638 | discontinued. | |
639 | ||
640 | #. **Topic:** Use the ``.. topic::`` directive to encapsulate text that is | |
641 | outside the main flow of the document. See the `topic directive`_ for | |
642 | additional details. | |
643 | ||
644 | ||
645 | TOC and Hyperlinks | |
646 | ------------------ | |
647 | ||
648 | All documents must be linked from another document or a table of contents, | |
649 | otherwise you will receive a warning when building the documentation. | |
650 | ||
651 | The Ceph project uses the ``.. toctree::`` directive. See `The TOC tree`_ | |
652 | for details. When rendering a TOC, consider specifying the ``:maxdepth:`` | |
653 | parameter so the rendered TOC is reasonably terse. | |
654 | ||
655 | Document authors should prefer to use the ``:ref:`` syntax where a link target | |
656 | contains a specific unique identifier (e.g., ``.. _unique-target-id:``), and a | |
657 | reference to the target specifically references the target (e.g., | |
658 | ``:ref:`unique-target-id```) so that if source files are moved or the | |
659 | information architecture changes, the links will still work. See | |
660 | `Cross referencing arbitrary locations`_ for details. | |
661 | ||
662 | Ceph documentation also uses the backtick (accent grave) character followed by | |
663 | the link text, another backtick and an underscore. Sphinx allows you to | |
664 | incorporate the link destination inline; however, we prefer to use the use the | |
665 | ``.. _Link Text: ../path`` convention at the bottom of the document, because it | |
666 | improves the readability of the document in a command line interface. | |
667 | ||
668 | ||
669 | .. _Python Sphinx: http://sphinx-doc.org | |
670 | .. _resturcturedText: http://docutils.sourceforge.net/rst.html | |
671 | .. _Fork and Pull: https://help.github.com/articles/using-pull-requests | |
672 | .. _github: http://github.com | |
673 | .. _ditaa: http://ditaa.sourceforge.net/ | |
674 | .. _Document Title: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle | |
675 | .. _Sections: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections | |
11fdf7f2 | 676 | .. _Cross referencing arbitrary locations: http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref |
7c673cae FG |
677 | .. _The TOC tree: http://sphinx-doc.org/markup/toctree.html |
678 | .. _Showing code examples: http://sphinx-doc.org/markup/code.html | |
679 | .. _paragraph level markup: http://sphinx-doc.org/markup/para.html | |
680 | .. _topic directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic |