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