7 You can help the Ceph project by contributing to the documentation. Even
8 small contributions help the Ceph project.
10 The easiest way to suggest a correction to the documentation is to send an
11 email to `ceph-users@ceph.io`. Include the string "ATTN: DOCS" or
12 "Attention: Docs" or "Attention: Documentation" in the subject line. In
13 the body of the email, include the text to be corrected (so that I can find
14 it in the repo) and include your correction.
16 Another way to suggest a documentation correction is to make a pull request.
17 The instructions for making a pull request against the Ceph documentation are
18 in the section :ref:`making_contributions`.
20 If this is your first time making an improvement to the documentation or
21 if you have noticed a small mistake (such as a spelling error or a typo),
22 it will be easier to send an email than to make a pull request. You will
23 be credited for the improvement unless you instruct Ceph Upstream
24 Documentation not to credit you.
26 Location of the Documentation in the Repository
27 ===============================================
29 The Ceph documentation source is in the ``ceph/doc`` directory of the Ceph
30 repository. Python Sphinx renders the source into HTML and manpages.
32 Viewing Old Ceph Documentation
33 ==============================
34 The https://docs.ceph.com link displays the latest release branch by default
35 (for example, if "Quincy" is the most recent release, then by default
36 https://docs.ceph.com displays the documentation for Quincy), but you can view
37 the documentation for older versions of Ceph (for example, ``pacific``) by
38 replacing the version name in the url (for example, ``quincy`` in
39 `https://docs.ceph.com/en/pacific <https://docs.ceph.com/en/quincy>`_) with the
40 branch name you prefer (for example, ``pacific``, to create a URL that reads
41 `https://docs.ceph.com/en/pacific/ <https://docs.ceph.com/en/pacific/>`_).
43 .. _making_contributions:
48 Making a documentation contribution involves the same basic procedure as making
49 a code contribution, with one exception: you must build documentation source
50 instead of compiling program source. This sequence (the sequence of building
51 the documentation source) includes the following steps:
56 #. `Build the Source`_
57 #. `Commit the Change`_
59 #. `Make a Pull Request`_
65 The source of the Ceph documentation is a collection of ReStructured Text files
66 that are in the Ceph repository in the ``ceph/doc`` directory. For details
67 on GitHub and Ceph, see :ref:`Get Involved`.
69 Use the `Fork and Pull`_ approach to make documentation contributions. To do
72 #. Install git locally. In Debian or Ubuntu, run the following command:
76 sudo apt-get install git
78 In Fedora, run the following command:
84 In CentOS/RHEL, run the following command:
90 #. Make sure that your ``.gitconfig`` file has been configured to include your
91 name and email address:
96 email = {your-email-address}
103 git config --global user.name "John Doe"
104 git config --global user.email johndoe@example.com
107 #. Create a `github`_ account (if you don't have one).
109 #. Fork the Ceph project. See https://github.com/ceph/ceph.
111 #. Clone your fork of the Ceph project to your local host. This creates what is
112 known as a "local working copy".
114 The Ceph documentation is organized by component:
116 - **Ceph Storage Cluster:** The Ceph Storage Cluster documentation is
117 in the ``doc/rados`` directory.
119 - **Ceph Block Device:** The Ceph Block Device documentation is in
120 the ``doc/rbd`` directory.
122 - **Ceph Object Storage:** The Ceph Object Storage documentation is in
123 the ``doc/radosgw`` directory.
125 - **Ceph File System:** The Ceph File System documentation is in the
126 ``doc/cephfs`` directory.
128 - **Installation (Quick):** Quick start documentation is in the
129 ``doc/start`` directory.
131 - **Installation (Manual):** Documentaton concerning the manual installation of
132 Ceph is in the ``doc/install`` directory.
134 - **Manpage:** Manpage source is in the ``doc/man`` directory.
136 - **Developer:** Developer documentation is in the ``doc/dev``
139 - **Images:** Images including JPEG and PNG files are stored in the
140 ``doc/images`` directory.
146 When you make small changes to the documentation, such as fixing typographical
147 errors or clarifying explanations, use the ``main`` branch (default). You
148 should also use the ``main`` branch when making contributions to features that
149 are in the current release. ``main`` is the most commonly used branch. :
155 When you make changes to documentation that affect an upcoming release, use
156 the ``next`` branch. ``next`` is the second most commonly used branch. :
162 When you are making substantial contributions such as new features that are not
163 yet in the current release; if your contribution is related to an issue with a
164 tracker ID; or, if you want to see your documentation rendered on the Ceph.com
165 website before it gets merged into the ``main`` branch, you should create a
166 branch. To distinguish branches that include only documentation updates, we
167 prepend them with ``wip-doc`` by convention, following the form
168 ``wip-doc-{your-branch-name}``. If the branch relates to an issue filed in
169 http://tracker.ceph.com/issues, the branch name incorporates the issue number.
170 For example, if a documentation branch is a fix for issue #4000, the branch name
171 should be ``wip-doc-4000`` by convention and the relevant tracker URL will be
172 http://tracker.ceph.com/issues/4000.
174 .. note:: Please do not mingle documentation contributions and source code
175 contributions in a single commit. When you keep documentation
176 commits separate from source code commits, it simplifies the review
177 process. We highly recommend that any pull request that adds a feature or
178 a configuration option should also include a documentation commit that
179 describes the changes.
181 Before you create your branch name, ensure that it doesn't already exist in the
182 local or remote repository. :
186 git branch -a | grep wip-doc-{your-branch-name}
188 If it doesn't exist, create your branch:
192 git checkout -b wip-doc-{your-branch-name}
198 Modifying a document involves opening a reStructuredText file, changing
199 its contents, and saving the changes. See `Documentation Style Guide`_ for
200 details on syntax requirements.
202 Adding a document involves creating a new reStructuredText file within the
203 ``doc`` directory tree with a ``*.rst``
204 extension. You must also include a reference to the document: a hyperlink
205 or a table of contents entry. The ``index.rst`` file of a top-level directory
206 usually contains a TOC, where you can add the new file name. All documents must
207 have a title. See `Headings`_ for details.
209 Your new document doesn't get tracked by ``git`` automatically. When you want
210 to add the document to the repository, you must use ``git add
211 {path-to-filename}``. For example, from the top level directory of the
212 repository, adding an ``example.rst`` file to the ``rados`` subdirectory would
217 git add doc/rados/example.rst
219 Deleting a document involves removing it from the repository with ``git rm
220 {path-to-filename}``. For example:
224 git rm doc/rados/example.rst
226 You must also remove any reference to a deleted document from other documents.
232 To build the documentation, navigate to the ``ceph`` repository directory:
240 The directory that contains ``build-doc`` and ``serve-doc`` must be included
241 in the ``PATH`` environment variable in order for these commands to work.
244 To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute:
250 To scan for the reachability of external links, execute:
254 admin/build-doc linkcheck
256 Executing ``admin/build-doc`` will create a ``build-doc`` directory under
257 ``ceph``. You may need to create a directory under ``ceph/build-doc`` for
258 output of Javadoc files:
262 mkdir -p output/html/api/libcephfs-java/javadoc
264 The build script ``build-doc`` will produce an output of errors and warnings.
265 You MUST fix errors in documents you modified before committing a change, and
266 you SHOULD fix warnings that are related to syntax you modified.
268 .. important:: You must validate ALL HYPERLINKS. If a hyperlink is broken,
269 it automatically breaks the build!
271 Once you build the documentation set, you may start an HTTP server at
272 ``http://localhost:8080/`` to view it:
278 You can also navigate to ``build-doc/output`` to inspect the built documents.
279 There should be an ``html`` directory and a ``man`` directory containing
280 documentation in HTML and manpage formats respectively.
282 Build the Source (First Time)
283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285 Ceph uses Python Sphinx, which is generally distribution agnostic. The first
286 time you build Ceph documentation, it will generate a doxygen XML tree, which
287 is a bit time consuming.
289 Python Sphinx does have some dependencies that vary across distributions. The
290 first time you build the documentation, the script will notify you if you do not
291 have the dependencies installed. To run Sphinx and build documentation successfully,
292 the following packages are required:
296 <style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style>
297 <table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3>
313 </td><td><h3>Fedora</h3>
331 </td><td><h3>CentOS/RHEL</h3>
348 </td></tr></tbody></table>
351 Install each dependency that is not installed on your host. For Debian/Ubuntu
352 distributions, execute the following:
356 sudo apt-get install gcc python-dev python3-pip libxml2-dev libxslt-dev doxygen graphviz ant ditaa
357 sudo apt-get install python3-sphinx python3-venv
359 For Fedora distributions, execute the following:
363 sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant
364 sudo pip install html2text
365 sudo yum install python-jinja2 python-pygments python-docutils python-sphinx
366 sudo yum install jericho-html ditaa
368 For CentOS/RHEL distributions, it is recommended to have ``epel`` (Extra
369 Packages for Enterprise Linux) repository as it provides some extra packages
370 which are not available in the default repository. To install ``epel``, execute
375 sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
377 For CentOS/RHEL distributions, execute the following:
381 sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant
382 sudo pip install html2text
384 For CentOS/RHEL distributions, the remaining python packages are not available
385 in the default and ``epel`` repositories. So, use http://rpmfind.net/ to find
386 the packages. Then, download them from a mirror and install them. For example:
390 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm
391 sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm
392 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm
393 sudo yum install python-pygments-1.4-9.el7.noarch.rpm
394 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
395 sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
396 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm
397 sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm
399 Ceph documentation makes extensive use of `ditaa`_, which is not presently built
400 for CentOS/RHEL7. You must install ``ditaa`` if you are making changes to
401 ``ditaa`` diagrams so that you can verify that they render properly before you
402 commit new or modified ``ditaa`` diagrams. You may retrieve compatible required
403 packages for CentOS/RHEL distributions and install them manually. To run
404 ``ditaa`` on CentOS/RHEL7, following dependencies are required:
410 Use http://rpmfind.net/ to find compatible ``ditaa`` and the dependencies.
411 Then, download them from a mirror and install them. For example:
415 wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm
416 sudo yum install jericho-html-3.3-4.fc22.noarch.rpm
417 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
418 sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
419 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm
420 sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm
421 wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm
422 sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm
424 Once you have installed all these packages, build the documentation by following
425 the steps given in `Build the Source`_.
431 Ceph documentation commits are simple, but follow a strict convention:
433 - A commit SHOULD have 1 file per commit (it simplifies rollback). You MAY
434 commit multiple files with related changes. Unrelated changes SHOULD NOT
435 be put into the same commit.
436 - A commit MUST have a comment.
437 - A commit comment MUST be prepended with ``doc:``. (strict)
438 - The comment summary MUST be one line only. (strict)
439 - Additional comments MAY follow a blank line after the summary,
441 - A commit MAY include ``Fixes: https://tracker.ceph.com/issues/{bug number}``.
442 - Commits MUST include ``Signed-off-by: Firstname Lastname <email>``. (strict)
444 .. tip:: Follow the foregoing convention particularly where it says
445 ``(strict)`` or you will be asked to modify your commit to comply with
448 The following is a common commit comment (preferred)::
450 doc: Fixes a spelling error and a broken hyperlink.
452 Signed-off-by: John Doe <john.doe@gmail.com>
455 The following comment includes a reference to a bug. ::
457 doc: Fixes a spelling error and a broken hyperlink.
459 Fixes: https://tracker.ceph.com/issues/1234
461 Signed-off-by: John Doe <john.doe@gmail.com>
464 The following comment includes a terse sentence following the comment summary.
465 There is a carriage return between the summary line and the description::
467 doc: Added mon setting to monitor config reference
469 Describes 'mon setting', which is a new setting added
472 Signed-off-by: John Doe <john.doe@gmail.com>
475 To commit changes, execute the following:
482 An easy way to manage your documentation commits is to use visual tools for
483 ``git``. For example, ``gitk`` provides a graphical interface for viewing the
484 repository history, and ``git-gui`` provides a graphical interface for viewing
485 your uncommitted changes, staging them for commit, committing the changes and
486 pushing them to your forked Ceph repository.
489 For Debian/Ubuntu, execute:
493 sudo apt-get install gitk git-gui
495 For Fedora/CentOS/RHEL, execute:
499 sudo yum install gitk git-gui
505 cd {git-ceph-repo-path}
508 Finally, select **File->Start git gui** to activate the graphical user interface.
514 Once you have one or more commits, you must push them from the local copy of the
515 repository to ``github``. A graphical tool like ``git-gui`` provides a user
516 interface for pushing to the repository. If you created a branch previously:
520 git push origin wip-doc-{your-branch-name}
532 As noted earlier, you can make documentation contributions using the `Fork and
536 Squash Extraneous Commits
537 -------------------------
538 Each pull request ought to be associated with only a single commit. If you have
539 made more than one commit to the feature branch that you are working in, you
540 will need to "squash" the multiple commits. "Squashing" is the colloquial term
541 for a particular kind of "interactive rebase". Squashing can be done in a great
542 number of ways, but the example here will deal with a situation in which there
543 are three commits and the changes in all three of the commits are kept. The three
544 commits will be squashed into a single commit.
546 #. Make the commits that you will later squash.
548 #. Make the first commit.
552 doc/glossary: improve "CephX" entry
554 Improve the glossary entry for "CephX".
556 Signed-off-by: Zac Dover <zac.dover@proton.me>
558 # Please enter the commit message for your changes. Lines starting
559 # with '#' will be ignored, and an empty message aborts the commit.
561 # On branch wip-doc-2023-03-28-glossary-cephx
562 # Changes to be committed:
563 # modified: glossary.rst
566 #. Make the second commit.
570 doc/glossary: add link to architecture doc
572 Add a link to a section in the architecture document, which link
573 will be used in the process of improving the "CephX" glossary entry.
575 Signed-off-by: Zac Dover <zac.dover@proton.me>
577 # Please enter the commit message for your changes. Lines starting
578 # with '#' will be ignored, and an empty message aborts the commit.
580 # On branch wip-doc-2023-03-28-glossary-cephx
581 # Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'.
583 # Changes to be committed:
584 # modified: architecture.rst
586 #. Make the third commit.
590 doc/glossary: link to Arch doc in "CephX" glossary
592 Link to the Architecture document from the "CephX" entry in the
595 Signed-off-by: Zac Dover <zac.dover@proton.me>
597 # Please enter the commit message for your changes. Lines starting
598 # with '#' will be ignored, and an empty message aborts the commit.
600 # On branch wip-doc-2023-03-28-glossary-cephx
601 # Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'.
603 # Changes to be committed:
604 # modified: glossary.rst
606 #. There are now three commits in the feature branch. We will now begin the
607 process of squashing them into a single commit.
609 #. Run the command ``git rebase -i main``, which rebases the current branch
610 (the feature branch) against the ``main`` branch:
616 #. A list of the commits that have been made to the feature branch now
617 appear, and looks like this:
621 pick d395e500883 doc/glossary: improve "CephX" entry
622 pick b34986e2922 doc/glossary: add link to architecture doc
623 pick 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
625 # Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)
628 # p, pick <commit> = use commit
629 # r, reword <commit> = use commit, but edit the commit message
630 # e, edit <commit> = use commit, but stop for amending
631 # s, squash <commit> = use commit, but meld into previous commit
632 # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
633 # commit's log message, unless -C is used, in which case
634 # keep only this commit's message; -c is same as -C but
636 # x, exec <command> = run command (the rest of the line) using shell
637 # b, break = stop here (continue rebase later with 'git rebase --continue')
638 # d, drop <commit> = remove commit
639 # l, label <label> = label current HEAD with a name
640 # t, reset <label> = reset HEAD to a label
641 # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
642 # create a merge commit using the original merge commit's
643 # message (or the oneline, if no original merge commit was
644 # specified); use -c <commit> to reword the commit message
645 # u, update-ref <ref> = track a placeholder for the <ref> to be updated
646 # to this position in the new commits. The <ref> is
647 # updated at the end of the rebase
649 # These lines can be re-ordered; they are executed from top to bottom.
651 # If you remove a line here THAT COMMIT WILL BE LOST.
653 Find the part of the screen that says "pick". This is the part that you will
654 alter. There are three commits that are currently labeled "pick". We will
655 choose one of them to remain labeled "pick", and we will label the other two
658 #. Label two of the three commits ``squash``:
662 pick d395e500883 doc/glossary: improve "CephX" entry
663 squash b34986e2922 doc/glossary: add link to architecture doc
664 squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
666 # Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)
669 # p, pick <commit> = use commit
670 # r, reword <commit> = use commit, but edit the commit message
671 # e, edit <commit> = use commit, but stop for amending
672 # s, squash <commit> = use commit, but meld into previous commit
673 # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
674 # commit's log message, unless -C is used, in which case
675 # keep only this commit's message; -c is same as -C but
677 # x, exec <command> = run command (the rest of the line) using shell
678 # b, break = stop here (continue rebase later with 'git rebase --continue')
679 # d, drop <commit> = remove commit
680 # l, label <label> = label current HEAD with a name
681 # t, reset <label> = reset HEAD to a label
682 # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
683 # create a merge commit using the original merge commit's
684 # message (or the oneline, if no original merge commit was
685 # specified); use -c <commit> to reword the commit message
686 # u, update-ref <ref> = track a placeholder for the <ref> to be updated
687 # to this position in the new commits. The <ref> is
688 # updated at the end of the rebase
690 # These lines can be re-ordered; they are executed from top to bottom.
692 # If you remove a line here THAT COMMIT WILL BE LOST.
694 #. Now we create a commit message that applies to all the commits that have
695 been squashed together:
697 #. When you save and close the list of commits that you have designated for
698 squashing, a list of all three commit messages appears, and it looks
703 # This is a combination of 3 commits.
704 # This is the 1st commit message:
706 doc/glossary: improve "CephX" entry
708 Improve the glossary entry for "CephX".
710 Signed-off-by: Zac Dover <zac.dover@proton.me>
712 # This is the commit message #2:
714 doc/glossary: add link to architecture doc
716 Add a link to a section in the architecture document, which link
717 will be used in the process of improving the "CephX" glossary entry.
719 Signed-off-by: Zac Dover <zac.dover@proton.me>
721 # This is the commit message #3:
723 doc/glossary: link to Arch doc in "CephX" glossary
725 Link to the Architecture document from the "CephX" entry in the
728 Signed-off-by: Zac Dover <zac.dover@proton.me>
730 # Please enter the commit message for your changes. Lines starting
731 # with '#' will be ignored, and an empty message aborts the commit.
733 # Date: Tue Mar 28 18:42:11 2023 +1000
735 # interactive rebase in progress; onto 0793495b9d1
736 # Last commands done (3 commands done):
737 # squash b34986e2922 doc/glossary: add link to architecture doc
738 # squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
739 # No commands remaining.
740 # You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'.
742 # Changes to be committed:
743 # modified: doc/architecture.rst
744 # modified: doc/glossary.rst
746 #. The commit messages have been revised into the simpler form presented here:
750 doc/glossary: improve "CephX" entry
752 Improve the glossary entry for "CephX".
754 Signed-off-by: Zac Dover <zac.dover@proton.me>
756 # Please enter the commit message for your changes. Lines starting
757 # with '#' will be ignored, and an empty message aborts the commit.
759 # Date: Tue Mar 28 18:42:11 2023 +1000
761 # interactive rebase in progress; onto 0793495b9d1
762 # Last commands done (3 commands done):
763 # squash b34986e2922 doc/glossary: add link to architecture doc
764 # squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
765 # No commands remaining.
766 # You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'.
768 # Changes to be committed:
769 # modified: doc/architecture.rst
770 # modified: doc/glossary.rst
772 #. Force push the squashed commit from your local working copy to the remote
773 upstream branch. The force push is necessary because the newly squashed commit
774 does not have an ancestor in the remote. If that confuses you, just run this
775 command and don't think too much about it:
783 Enumerating objects: 9, done.
784 Counting objects: 100% (9/9), done.
785 Delta compression using up to 8 threads
786 Compressing objects: 100% (5/5), done.
787 Writing objects: 100% (5/5), 722 bytes | 722.00 KiB/s, done.
788 Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
789 remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
790 To github.com:zdover23/ceph.git
791 + b34986e2922...02e3a5cb763 wip-doc-2023-03-28-glossary-cephx -> wip-doc-2023-03-28-glossary-cephx (forced update)
800 If some time has passed and the pull request that you raised has not been
801 reviewed, contact the component lead and ask what's taking so long. See
802 :ref:`ctl` for a list of component leads.
804 Documentation Style Guide
805 =========================
807 One objective of the Ceph documentation project is to ensure the readability of
808 the documentation in both native reStructuredText format and its rendered
809 formats such as HTML. Navigate to your Ceph repository and view a document in
810 its native format. You may notice that it is generally as legible in a terminal
811 as it is in its rendered HTML format. Additionally, you may also notice that
812 diagrams in ``ditaa`` format also render reasonably well in text mode. :
816 less doc/architecture.rst
818 Review the following style guides to maintain this consistency.
824 #. **Document Titles:** Document titles use the ``=`` character overline and
825 underline with a leading and trailing space on the title text line.
826 See `Document Title`_ for details.
828 #. **Section Titles:** Section tiles use the ``=`` character underline with no
829 leading or trailing spaces for text. Two carriage returns should precede a
830 section title (unless an inline reference precedes it). See `Sections`_ for
833 #. **Subsection Titles:** Subsection titles use the ``_`` character underline
834 with no leading or trailing spaces for text. Two carriage returns should
835 precede a subsection title (unless an inline reference precedes it).
841 As a general rule, we prefer text to wrap at column 80 so that it is legible in
842 a command line interface without leading or trailing white space. Where
843 possible, we prefer to maintain this convention with text, lists, literal text
844 (exceptions allowed), tables, and ``ditaa`` graphics.
846 #. **Paragraphs**: Paragraphs have a leading and a trailing carriage return,
847 and should be 80 characters wide or less so that the documentation can be
848 read in native format in a command line terminal.
850 #. **Literal Text:** To create an example of literal text (e.g., command line
851 usage), terminate the preceding paragraph with ``::`` or enter a carriage
852 return to create an empty line after the preceding paragraph; then, enter
853 ``::`` on a separate line followed by another empty line. Then, begin the
854 literal text with tab indentation (preferred) or space indentation of 3
857 #. **Indented Text:** Indented text such as bullet points
858 (e.g., ``- some text``) may span multiple lines. The text of subsequent
859 lines should begin at the same character position as the text of the
860 indented text (less numbers, bullets, etc.).
862 Indented text may include literal text examples. Whereas, text indentation
863 should be done with spaces, literal text examples should be indented with
864 tabs. This convention enables you to add an additional indented paragraph
865 following a literal example by leaving a blank line and beginning the
866 subsequent paragraph with space indentation.
868 #. **Numbered Lists:** Numbered lists should use autonumbering by starting
869 a numbered indent with ``#.`` instead of the actual number so that
870 numbered paragraphs can be repositioned without requiring manual
873 #. **Code Examples:** Ceph supports the use of the
874 ``.. code-block::<language>`` role, so that you can add highlighting to
875 source examples. This is preferred for source code. However, use of this
876 tag will cause autonumbering to restart at 1 if it is used as an example
877 within a numbered list. See `Showing code examples`_ for details.
880 Paragraph Level Markup
881 ----------------------
883 The Ceph project uses `paragraph level markup`_ to highlight points.
885 #. **Tip:** Use the ``.. tip::`` directive to provide additional information
886 that assists the reader or steers the reader away from trouble.
888 #. **Note**: Use the ``.. note::`` directive to highlight an important point.
890 #. **Important:** Use the ``.. important::`` directive to highlight important
891 requirements or caveats (e.g., anything that could lead to data loss). Use
892 this directive sparingly, because it renders in red.
894 #. **Version Added:** Use the ``.. versionadded::`` directive for new features
895 or configuration settings so that users know the minimum release for using
898 #. **Version Changed:** Use the ``.. versionchanged::`` directive for changes
899 in usage or configuration settings.
901 #. **Deprecated:** Use the ``.. deprecated::`` directive when CLI usage,
902 a feature or a configuration setting is no longer preferred or will be
905 #. **Topic:** Use the ``.. topic::`` directive to encapsulate text that is
906 outside the main flow of the document. See the `topic directive`_ for
910 Table of Contents (TOC) and Hyperlinks
911 ---------------------------------------
913 The documents in the Ceph documentation suite follow certain conventions that
914 are explained in this section.
916 Every document (every ``.rst`` file) in the Sphinx-controlled Ceph
917 documentation suite must be linked either (1) from another document in the
918 documentation suite or (2) from a table of contents (TOC). If any document in
919 the documentation suite is not linked in this way, the ``build-doc`` script
920 generates warnings when it tries to build the documentation.
922 The Ceph project uses the ``.. toctree::`` directive. See `The TOC tree`_ for
923 details. When rendering a table of contents (TOC), specify the ``:maxdepth:``
924 parameter so that the rendered TOC is not too long.
926 Use the ``:ref:`` syntax where a link target contains a specific unique
927 identifier (for example, ``.. _unique-target-id:``). A link to the section
928 designated by ``.. _unique-target-id:`` looks like this:
929 ``:ref:`unique-target-id```. If this convention is followed, the links within
930 the ``.rst`` source files will work even if the source files are moved within
931 the ``ceph/doc`` directory. See `Cross referencing arbitrary locations`_ for
934 .. _start_external_hyperlink_example:
936 External Hyperlink Example
937 ~~~~~~~~~~~~~~~~~~~~~~~~~~
939 It is also possible to create a link to a section of the documentation and to
940 have custom text appear in the body of the link. This is useful when it is more
941 important to preserve the text of the sentence containing the link than it is
942 to refer explicitly to the title of the section being linked to.
944 For example, RST that links to the Sphinx Python Document Generator homepage
945 and generates a sentence reading "Click here to learn more about Python
946 Sphinx." looks like this:
950 ``Click `here <https://www.sphinx-doc.org>`_ to learn more about Python
953 And here it is, rendered:
955 Click `here <https://www.sphinx-doc.org>`_ to learn more about Python Sphinx.
957 Pay special attention to the underscore after the backtick. If you forget to
958 include it and this is your first day working with RST, there's a chance that
959 you'll spend all day wondering what went wrong without realizing that you
960 omitted that underscore. Also, pay special attention to the space between the
961 substitution text (in this case, "here") and the less-than bracket that sets
962 the explicit link apart from the substition text. The link will not render
963 properly without this space.
968 By a custom established when Ceph was still being developed by Inktank,
969 contributors to the documentation of the Ceph project preferred to use the
970 convention of putting ``.. _Link Text: ../path`` links at the bottom of the
971 document and linking to them using references of the form ``:ref:`path```. This
972 convention was preferred because it made the documents more readable in a
973 command line interface. As of 2023, though, we have no preference for one over
974 the other. Use whichever convention makes the text easier to read.
976 Using a part of a sentence as a hyperlink, `like this <docs.ceph.com>`_, is
977 discouraged. The convention of writing "See X" is preferred. Here are some
978 preferred formulations:
980 #. For more information, see `docs.ceph.com <docs.ceph.com>`_.
982 #. See `docs.ceph.com <docs.ceph.com>`_.
985 Quirks of ReStructured Text
986 ---------------------------
991 .. _external_link_with_inline_text:
993 Use the formula immediately below to render links that direct the reader to
994 addresses external to the Ceph documentation:
998 `inline text <http:www.foo.com>`_
1000 .. note:: Do not fail to include the space between the inline text and the
1003 Do not fail to include the underscore after the final backtick.
1005 To link to addresses that are external to the Ceph documentation, include a
1006 space between the inline text and the angle bracket that precedes the
1007 external address. This is precisely the opposite of the convention for
1008 inline text that links to a location inside the Ceph documentation. See
1009 :ref:`here <internal_link_with_inline_text>` for an exemplar of this
1012 If this seems inconsistent and confusing to you, then you're right. It is
1013 inconsistent and confusing.
1015 See also ":ref:`External Hyperlink Example<start_external_hyperlink_example>`".
1020 To link to a section in the Ceph documentation, you must (1) define a target
1021 link before the section and then (2) link to that target from another location
1022 in the documentation. Here are the formulas for targets and links to those
1029 Title of Targeted Section
1030 =========================
1038 .. _internal_link_with_inline_text:
1040 Link to target with inline text::
1042 :ref:`inline text<target>`
1046 There is no space between "inline text" and the angle bracket that
1047 immediately follows it. This is precisely the opposite of :ref:`the
1048 convention for inline text that links to a location outside of the Ceph
1049 documentation<external_link_with_inline_text>`. If this seems inconsistent
1050 and confusing to you, then you're right. It is inconsistent and confusing.
1052 Escaping Bold Characters within Words
1053 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1055 This section explains how to make certain letters within a word bold while
1056 leaving the other letters in the word regular (non-bold).
1058 The following single-line paragraph provides an example of this:
1060 **C**\eph **F**\ile **S**\ystem.
1062 In ReStructured Text, the following formula will not work:
1066 **C**eph **F**ile **S**ystem
1068 The bolded notation must be turned off by means of the escape character (\\), as shown here:
1072 **C**\eph **F**\ile **S**\ystem
1074 .. _Python Sphinx: https://www.sphinx-doc.org
1075 .. _restructuredText: http://docutils.sourceforge.net/rst.html
1076 .. _Fork and Pull: https://help.github.com/articles/using-pull-requests
1077 .. _github: http://github.com
1078 .. _ditaa: http://ditaa.sourceforge.net/
1079 .. _Document Title: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle
1080 .. _Sections: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections
1081 .. _Cross referencing arbitrary locations: http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
1082 .. _The TOC tree: http://sphinx-doc.org/markup/toctree.html
1083 .. _Showing code examples: http://sphinx-doc.org/markup/code.html
1084 .. _paragraph level markup: http://sphinx-doc.org/markup/para.html
1085 .. _topic directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic