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