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