Notice

This document is for a development version of Ceph.

Documenting Ceph

You can help the Ceph project by contributing to the documentation. Even small contributions help the Ceph project.

The easiest way to suggest a correction to the documentation is to send an email to ceph-users@ceph.io. Include the string “ATTN: DOCS” or “Attention: Docs” or “Attention: Documentation” in the subject line. In the body of the email, include the text to be corrected (so that I can find it in the repo) and include your correction.

Another way to suggest a documentation correction is to make a pull request. The instructions for making a pull request against the Ceph documentation are in the section Making Contributions.

If this is your first time making an improvement to the documentation or if you have noticed a small mistake (such as a spelling error or a typo), it will be easier to send an email than to make a pull request. You will be credited for the improvement unless you instruct Ceph Upstream Documentation not to credit you.

Location of the Documentation in the Repository

The Ceph documentation source is in the ceph/doc directory of the Ceph repository. Python Sphinx renders the source into HTML and manpages.

Viewing Old Ceph Documentation

The https://docs.ceph.com site displays the latest documentation by default, i.e. main. This may include changes that have not yet been incorporated in any release. To view the documentation for older releases of Ceph (for example, quincy) by replacing the release name in the URL (for example, reef in https://docs.ceph.com/en/reef/) with the branch name you prefer (for example, quincy, to create a URL that reads https://docs.ceph.com/en/quincy/).

Alternately, a version chooser is presented at the lower right of the browser window.

Making Contributions

Making a documentation contribution involves the same basic procedure as making a code contribution. Corrections of spelling or grammar, improvements to wording, and addition / correction of modest amounts of material to existing pages do not require a local docs build. For such contributions, you may skip the Build the Source section below.

When adding or rearranging entire sections, or altering the underpinnings of the documentation site, you are encouraged to perform a local build of the documentation source. This sequence includes the following steps:

Get the Source
Select a Branch
Make a Change
Build the Source
Commit the Change
Push the Change
Make a Pull Request
Notify Us

Get the Source

The source of Ceph documentation is a collection of ReStructured Text files in the Ceph repository within the doc directory. For details on GitHub and Ceph, see Get Involved in the Ceph Community!.

Use the Fork and Pull approach to make documentation contributions. To do this, you must:

Install git locally. In Debian or Ubuntu, run the following command:
```
sudo apt-get install git
```
In Fedora, run the following command:
```
sudo yum install git
```
In CentOS/RHEL, run the following command:
```
sudo yum install git
```

Make sure that your .gitconfig file has been configured to include your name and email address:

[user]
   email = {your-email-address}
   name = {your-name}

For example:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

Create a GitHub account (if you don’t have one).
Fork the Ceph project. See https://github.com/ceph/ceph.
Clone your fork of the Ceph project to your local host. This creates what is known as a local working copy.

Ceph documentation is organized by component:

Ceph Storage Cluster: The Ceph Storage Cluster documentation is in the doc/rados directory.
Ceph Block Device: The Ceph Block Device documentation is in the doc/rbd directory.
Ceph Object Storage: The Ceph Object Storage documentation is in the doc/radosgw directory.
Ceph File System: The Ceph File System documentation is in the doc/cephfs directory.
Installation (Quick): Quick start documentation is in the doc/start directory.
Installation (Manual): Documentation concerning the manual installation of Ceph is in the doc/install directory.
Manpage: Manpage source is in the doc/man directory.
Developer: Developer documentation is in the doc/dev directory.
Images: Images including JPEG and PNG files are stored in the doc/images directory.

Select a Branch

When you make changes to the documentation, create a new and unique branch. To distinguish branches that include only documentation updates, we prepend them with wip-doc by convention, following the form wip-doc-{your-branch-name}. If the branch relates to an issue filed in http://tracker.ceph.com/issues, the branch name incorporates the issue number. For example, if a documentation branch is a fix for issue #4000, the branch name should be wip-doc-4000 by convention and the relevant tracker URL will be http://tracker.ceph.com/issues/4000.

Note

Please do not mingle documentation contributions and source code contributions in a single commit. When you keep documentation commits separate from source code commits, it simplifies the review process. We highly recommend that any pull request that adds a feature or a configuration option should also include a documentation commit that describes the changes.

Before you create your branch, ensure that it doesn’t already exist in the local or remote repository.

git branch -a | grep wip-doc-{your-branch-name}

If it doesn’t exist, create your branch:

git checkout -b wip-doc-{your-branch-name}

Make a Change

Modifying a document involves opening a reStructuredText file, changing its contents, and saving the changes. See Documentation Style Guide for details on syntax requirements.

Adding a document involves creating a new reStructuredText file within the doc directory tree with a *.rst extension. You must also include a reference to the document: a hyperlink or a table of contents entry. The index.rst file of a top-level directory usually contains a TOC, where you can add the new file name. All documents must have a title. See Headings for details.

Your new document doesn’t get tracked by git automatically. When you want to add the document to the repository, you must use git add {path-to-filename}. For example, from the top level directory of the repository, adding an example.rst file to the rados subdirectory would look like this:

git add doc/rados/example.rst

Deleting a document involves removing it from the repository with git rm {path-to-filename}. For example:

git rm doc/rados/example.rst

You must also remove any reference to a deleted document from other documents.

Build the Source

This is not necessary for modest documentation pull requests, but is encouraged for sweeping changes across many pages, or to the underpinnings of how the documentation site is built. Alternately, one may watch the GitHub page for a PR, as PR checks will compile a new, provisional site build that may be viewed before merging or reviewing. Note that once a link to the provisional build appears in the PR update messages, it may still take some time, as long as an hour, for the built site to render with the new changes. To view the rendered site, click the “three dots” icon then “View Details” for the ReadTheDocs check under GitHub Status Checks. If the build is not yet finished, the ReadTheDocs job status/build log will be shown.

If you choose to build the documentation, navigate to the ceph repository directory:

cd ceph

Note

The directory that contains build-doc and serve-doc must be included in the PATH environment variable in order for these commands to work.

To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute:

admin/build-doc

To scan for the reachability of external links, execute:

admin/build-doc linkcheck

Running admin/build-doc creates a build-doc directory under ceph. You may need to create a directory under ceph/build-doc for Javadoc file output:

mkdir -p output/html/api/libcephfs-java/javadoc

The build script build-doc produces output partially consisting of errors and warnings. You MUST fix errors in documents you modified before committing a change, and you SHOULD fix warnings that are related to syntax you modified.

Important

You must validate ALL HYPERLINKS. If a hyperlink is broken, it automatically breaks the build!

After you have built the documentation set, you may start an HTTP server at http://localhost:8080/ to view it by running the following command:

admin/serve-doc

You can also navigate to build-doc/output to inspect the built documents. Within build-doc/output is an html directory and a man directory containing documentation in HTML and manpage formats respectively.

Build the Source (First Time)

Ceph uses Python Sphinx, which is distribution agnostic. The first time you build the Ceph documentation, a doxygen XML tree is generated. This can be time-consuming.

Some of Python Sphinx’s dependencies vary across distributions. The first time you build the documentation, the build script notifies you of uninstalled dependencies.

To run Sphinx and build documentation successfully, the following packages are required:

Debian/Ubuntu

gcc
python3-dev
python3-pip
python3-sphinx
python3-venv
libxml2-dev
libxslt1-dev
doxygen
graphviz
ant
ditaa
cython3

Fedora

gcc
python-devel
python-pip
python-docutils
python-jinja2
python-pygments
python-sphinx
libxml2-devel
libxslt1-devel
doxygen
graphviz
ant
ditaa

CentOS/RHEL

gcc
python-devel
python-pip
python-docutils
python-jinja2
python-pygments
python-sphinx
libxml2-dev
libxslt1-dev
doxygen
graphviz
ant

Install each dependency that is not installed on your host. For Debian/Ubuntu distributions, run the following commands:

sudo apt-get install gcc python-dev python3-pip libxml2-dev libxslt-dev doxygen graphviz ant ditaa
sudo apt-get install python3-sphinx python3-venv cython3

For Fedora distributions, run the following commands:

sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant
sudo pip install html2text
sudo yum install python-jinja2 python-pygments python-docutils python-sphinx
sudo yum install jericho-html ditaa

For CentOS/RHEL distributions, it is recommended to enable the epel (Extra Packages for Enterprise Linux) repository, because it provides extra packages not available in the default repository. To install epel, run the following command:

sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

For CentOS/RHEL distributions, run the following commands:

sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant
sudo pip install html2text

For CentOS/RHEL distributions, the remaining Python packages are not available in the default repositories or the epel repositories. Use http://rpmfind.net/ to find the packages. Then download them from a mirror and install them. For example:

wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm
sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm
wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm
sudo yum install python-pygments-1.4-9.el7.noarch.rpm
wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm
sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm

Ceph documentation makes extensive use of ditaa, which is not built for CentOS/RHEL. If you make changes to ditaa diagrams, you must install ditaa to verify that they render properly before you commit your changes. You may retrieve compatible required packages for CentOS/RHEL distributions and install them manually. To run ditaa on CentOS/RHEL, following dependencies are required:

jericho-html
jai-imageio-core
batik

Use http://rpmfind.net/ to find compatible ditaa and its dependencies. Then download them from a mirror and install them. For example:

wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm
sudo yum install jericho-html-3.3-4.fc22.noarch.rpm
wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm
sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm
wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm
sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm

After you have installed these packages, build the documentation by following the steps in Build the Source.

Commit the Change

Ceph documentation commits are simple, but follow a strict convention:

When ready for merging, a PR SHOULD have a single commit. This may be acheived by amending an initial commit and force-pushing, or by adding additional commits then squashing. You MAY commit multiple files with related changes. Unrelated changes SHOULD NOT be put into the same commit or PR.
A commit MUST have a comment, which should match the PR title.
Both PR titles and commit titles should be imperatives, for example doc/rados: Fix a typo in foo.rst instead of doc/rados: Fixed a typo in foo.rst.
A commit comment MUST be prepended with doc:. (strict)
A documentation commit message SHOULD begin with the highest subdirectory that comprises all files changed. For example, if multiple files under doc/rados are changed, the appropriate title is of the form doc/rados: Update xxx. When changing a single file, it is good practice to call out that file, for example doc/rados: Fixed a typo in foo.rst. When a PR touches files at the top level, a title that begins only with doc: is reasonable.
The comment summary MUST be one line only. (strict)
Additional comments MAY follow a blank line after the summary, but should be concise.
A commit MUST include Fixes: https://tracker.ceph.com/issues/{bug number} if it addresses an open tracker issue.
Commits MUST include Signed-off-by: Firstname Lastname <email>. (strict)

Tip

Follow the foregoing convention particularly where it says (strict) or you will be asked to modify your commit to comply with this convention.

The following is a common commit comment (preferred):

doc: Fix a spelling error and a broken hyperlink

Signed-off-by: John Doe <john.doe@gmail.com>

The following comment includes a reference to a bug.

doc: Fix a spelling error and a broken hyperlink

Fixes: https://tracker.ceph.com/issues/1234

Signed-off-by: John Doe <john.doe@gmail.com>

The following comment includes a concise sentence following the comment summary. There is a carriage return between the summary line and the description:

doc/mon: Add new config option mon_blurfl to monitor config reference

Describes 'mon_blurfl', which is a new config option

Signed-off-by: John Doe <john.doe@gmail.com>

To commit changes, execute the following:

git commit -a

An easy way to manage your documentation commits is to use visual tools for git. For example, gitk provides a graphical interface for viewing the repository history, and git-gui provides a graphical interface for viewing your uncommitted changes, staging them for commit, committing the changes and pushing them to your forked Ceph repository. Note that these are entirely optional, you may stick with old-school CLI commands.

For Debian/Ubuntu, execute:

sudo apt-get install gitk git-gui

For Fedora/CentOS/RHEL, execute:

sudo yum install gitk git-gui

Then, execute:

cd {git-ceph-repo-path}
gitk

Finally, select File->Start git gui to activate the graphical user interface.

Push the Change

Once you have one or more commits, you must push them from the local copy of the repository to GitHub. A graphical tool like git-gui provides a user interface for pushing to the repository. If you created a branch previously:

git push origin wip-doc-{your-branch-name}

Otherwise:

git push

Make a Pull Request

As noted earlier, make documentation contributions using the Fork and Pull approach.

Squash Extraneous Commits

Each pull request that is ready to merge should feature a single commit, or at most one commit for source code (anything under the src directory) and one for docs. If you have made more than one commit to the feature branch that you are working in, you will need to “squash” the multiple commits. “Squashing” is the colloquial term for a particular kind of “interactive rebase”. Squashing can be done in a great number of ways, but the example here will deal with a situation in which there are three commits and the changes in all three of the commits are kept. The three commits will be squashed into a single commit.

Make the commits that you will later squash.

Make the first commit.

doc/glossary: improve "CephX" entry

Improve the glossary entry for "CephX".

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch wip-doc-2023-03-28-glossary-cephx
# Changes to be committed:
#       modified:   glossary.rst
#

Make the second commit.

doc/glossary: add link to architecture doc

Add a link to a section in the architecture document, which link
will be used in the process of improving the "CephX" glossary entry.

Signed-off-by: Zac Dover <zac.dover@proton.me>

   # Please enter the commit message for your changes. Lines starting
   # with '#' will be ignored, and an empty message aborts the commit.
   #
   # On branch wip-doc-2023-03-28-glossary-cephx
   # Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'.
   #
   # Changes to be committed:
   #       modified:   architecture.rst

Make the third commit.

doc/glossary: link to Arch doc in "CephX" glossary

Link to the Architecture document from the "CephX" entry in the
Glossary.

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch wip-doc-2023-03-28-glossary-cephx
# Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'.
#
# Changes to be committed:
#       modified:   glossary.rst

There are now three commits in the feature branch. We will now begin the process of squashing them into a single commit.

Run the command git rebase -i main, which rebases the current branch (the feature branch) against the main branch:
```
git rebase -i main
```

A list of the commits that have been made to the feature branch now appear, and looks like this:

pick d395e500883 doc/glossary: improve "CephX" entry
pick b34986e2922 doc/glossary: add link to architecture doc
pick 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary

# Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
#         create a merge commit using the original merge commit's
#         message (or the oneline, if no original merge commit was
#         specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
#                       to this position in the new commits. The <ref> is
#                       updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.

Find the part of the screen that says “pick”. This is the part that you will alter. There are three commits that are currently labeled “pick”. We will choose one of them to remain labeled “pick”, and we will label the other two commits “squash”.

Label two of the three commits squash:

pick d395e500883 doc/glossary: improve "CephX" entry
squash b34986e2922 doc/glossary: add link to architecture doc
squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary

# Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
#         create a merge commit using the original merge commit's
#         message (or the oneline, if no original merge commit was
#         specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
#                       to this position in the new commits. The <ref> is
#                       updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.

Now we create a commit message that applies to all the commits that have been squashed together:

When you save and close the list of commits that you have designated for squashing, a list of all three commit messages appears, and it looks like this:

# This is a combination of 3 commits.
# This is the 1st commit message:

doc/glossary: improve "CephX" entry

Improve the glossary entry for "CephX".

Signed-off-by: Zac Dover <zac.dover@proton.me>

# This is the commit message #2:

doc/glossary: add link to architecture doc

Add a link to a section in the architecture document, which link
will be used in the process of improving the "CephX" glossary entry.

Signed-off-by: Zac Dover <zac.dover@proton.me>

# This is the commit message #3:

doc/glossary: link to Arch doc in "CephX" glossary

Link to the Architecture document from the "CephX" entry in the
Glossary.

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Tue Mar 28 18:42:11 2023 +1000
#
# interactive rebase in progress; onto 0793495b9d1
# Last commands done (3 commands done):
#    squash b34986e2922 doc/glossary: add link to architecture doc
#    squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
# No commands remaining.
# You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'.
#
# Changes to be committed:
#       modified:   doc/architecture.rst
#       modified:   doc/glossary.rst

The commit messages have been revised into the simpler form presented here:

doc/glossary: improve "CephX" entry

Improve the glossary entry for "CephX".

Signed-off-by: Zac Dover <zac.dover@proton.me>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Tue Mar 28 18:42:11 2023 +1000
#
# interactive rebase in progress; onto 0793495b9d1
# Last commands done (3 commands done):
#    squash b34986e2922 doc/glossary: add link to architecture doc
#    squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary
# No commands remaining.
# You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'.
#
# Changes to be committed:
#       modified:   doc/architecture.rst
#       modified:   doc/glossary.rst

Force push the squashed commit from your local working copy to the remote upstream branch. The force push is necessary because the newly squashed commit does not have an ancestor in the remote. If that confuses you, just run this command and don’t think too much about it:

git push -f

Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 722 bytes | 722.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To github.com:zdover23/ceph.git
 + b34986e2922...02e3a5cb763 wip-doc-2023-03-28-glossary-cephx -> wip-doc-2023-03-28-glossary-cephx (forced update)

Notify Us

If some time has passed and the pull request that you raised has not been reviewed, contact the component lead and ask what’s taking so long. See Component Team Leads for a list of component leads.

Documentation Style Guide

One objective of the Ceph documentation project is to ensure the readability of the documentation in both native reStructuredText format and its rendered formats such as HTML. Navigate to your Ceph repository and view a document in its native format. You may notice that it is generally as legible in a terminal as it is in its rendered HTML format. Additionally, you may also notice that diagrams in ditaa format also render reasonably well in text mode.

less doc/architecture.rst

Review the following style guides to maintain this consistency.

Headings

Document Titles: Document titles use the = character overline and underline with a leading and trailing space on the title text line. See Document Title for details.
Section Titles: Section titles use the = character underline with no leading or trailing spaces for text. Two carriage returns should precede a section title (unless an inline reference precedes it). See Sections for details.
Subsection Titles: Subsection titles use the _ character underline with no leading or trailing spaces for text. Two carriage returns should precede a subsection title (unless an inline reference precedes it).

Text Body

We prefer text in .rst files to wrap at column 80 so that it is legible in a command line interface without leading or trailing white space. This also cultivates clear PR reviews and edits. Where possible, we prefer to maintain this convention with text, lists, literal text (exceptions allowed), tables, and ditaa graphics.

Paragraphs: Paragraphs have a leading and a trailing carriage return, and should be 80 characters wide or less so that the documentation can be read in native format in a command line terminal.
Literal Text: To create an example of literal text (e.g., command line usage), terminate the preceding paragraph with :: or enter a carriage return to create an empty line after the preceding paragraph; then, enter :: on a separate line followed by another empty line. Then, begin the literal text with tab indentation (preferred) or space indentation of 3 characters.
Indented Text: Indented text such as bullet points (e.g., - some text) may span multiple lines. The text of subsequent lines should begin at the same character position as the text of the indented text (less numbers, bullets, etc.).

Indented text may include literal text examples. Although text indentation should be done with spaces, literal text examples should be indented with tabs. This convention enables you to add an additional indented paragraph following a literal example by leaving a blank line and beginning the subsequent paragraph with space indentation.
Numbered Lists: Numbered lists should use autonumbering by starting a numbered indent with #. instead of the actual number so that numbered paragraphs can be repositioned without requiring manual renumbering.
Code Examples: Ceph supports the use of the .. code-block::<language> role, so that you can add highlighting to source examples. This is preferred for source code. However, use of this tag will cause autonumbering to restart at 1 if it is used as an example within a numbered list. See Showing code examples for details.

Paragraph Level Markup

The Ceph project uses paragraph level markup to highlight points.

Tip: Use the .. tip:: directive to provide additional information that assists the reader or steers the reader away from trouble.
Note: Use the .. note:: directive to highlight an important point.
Important: Use the .. important:: directive to highlight important requirements or caveats (e.g., anything that could lead to data loss). Use this directive sparingly, because it renders in red.
Version Added: Use the .. versionadded:: directive for new features or configuration settings so that users know the minimum release for using a feature.
Version Changed: Use the .. versionchanged:: directive for changes in usage or configuration settings.
Deprecated: Use the .. deprecated:: directive when CLI usage, a feature or a configuration setting is no longer preferred or will be discontinued.
Topic: Use the .. topic:: directive to encapsulate text that is outside the main flow of the document. See the topic directive for additional details.

Table of Contents (TOC) and Hyperlinks

The documents in the Ceph documentation suite follow certain conventions that are explained in this section.

Every document (every .rst file) in the Sphinx-controlled Ceph documentation suite must be linked either (1) from another document in the documentation suite or (2) from a table of contents (TOC). If any document in the documentation suite is not linked in this way, the build-doc script generates warnings when it tries to build the documentation.

The Ceph project uses the .. toctree:: directive. See The TOC tree for details. When rendering a table of contents (TOC), specify the :maxdepth: parameter so that the rendered TOC is not too long.

Use the :ref: syntax where a link target contains a specific unique identifier (for example, .. _unique-target-id:). A link to the section designated by .. _unique-target-id: looks like this: :ref:`unique-target-id`. If this convention is followed, the links within the .rst source files will work even if the source files are moved within the ceph/doc directory. See Cross referencing arbitrary locations for details.

External Hyperlink Example

It is also possible to create a link to a section of the documentation and to have custom text appear in the body of the link. This is useful when it is more important to preserve the text of the sentence containing the link than it is to refer explicitly to the title of the section being linked to.

For example, RST that links to the Sphinx Python Document Generator homepage and generates a sentence reading “Click here to learn more about Python Sphinx.” looks like this:

Click `here <https://www.sphinx-doc.org>`_ to learn more about Python
Sphinx.

And here it is, rendered:

Click here to learn more about Python Sphinx.

Pay special attention to the underscore after the backtick. If you forget to include it and this is your first day working with RST, there’s a chance that you’ll spend all day wondering what went wrong without realizing that you omitted that underscore. Also, pay special attention to the space between the substitution text (in this case, “here”) and the less-than bracket that sets the explicit link apart from the substitution text. The link will not render properly without this space.

Linking Customs

By a custom established when Ceph was still being developed by Inktank, contributors to the documentation of the Ceph project preferred to use the convention of putting .. _Link Text: ../path links at the bottom of the document and linking to them using references of the form :ref:`path`. This convention was preferred because it made the documents more readable in a command line interface. As of 2023, though, we have no preference for one over the other. Use whichever convention makes the text easier to read.

Using a part of a sentence as a hyperlink, like this, is discouraged. The convention of writing “See X” is preferred. Here are some preferred formulations:

For more information, see docs.ceph.com.
See docs.ceph.com.

Conventions

The below are conventions that we try to maintain within the Ceph documentation. You may find deviations from these conventions within the documentation. If so, please ensure that you are looking at the latest files in the main branch. Corrections may be entered as a PR or by asking in #ceph-doc in the Ceph Slack workspace.

While the Ceph project is worldwide, we maintain the documentation in North American English.
It is common in the community to refer to Ceph Monitor daemons as _mons_, we prefer _Monitors_ in the documentation.
Similarly _mgrs_ are Managers
The plural of MDS is awkward; the best we’ve come up with is MDSes.
When writing a command example that the reader would enter as-is, preface with text like _To recombinate the zoplex levels, run the following command:_
When writing a command example into which the reader should interpolate RADOS pool names, host names, etc., preface with text like _To recombinate the zoplex levels for a single pool, run a command of the following form:_
Numbers greater than one hundred may be written with digits, for example 1024.
Numbers smaller than one hundred should be spelled out unless they are literals to be included in option settings or commands.

Quirks of ReStructured Text

External Links

Use the formula immediately below to render links that direct the reader to addresses external to the Ceph documentation:

`inline text <https://www.foo.com>`_

Note

Do not fail to include the space between the inline text and the less-than sign.

Do not fail to include the underscore after the final backtick.

To link to addresses that are external to the Ceph documentation, include a space between the inline text and the angle bracket that precedes the external address. This is precisely the opposite of the convention for inline text that links to a location inside the Ceph documentation. See here for an exemplar of this convention.

If this seems inconsistent and confusing to you, then you’re right. It is inconsistent and confusing.

See also “External Hyperlink Example”.

Internal Links

To link to a section in the Ceph documentation, you must (1) define a target link before the section and then (2) link to that target from another location in the documentation. Here are the formulas for targets and links to those targets:

Target:

.. _target:

Title of Targeted Section
=========================

Lorem ipsum...

Link to target:

:ref:`target`

Link to target with inline text:

:ref:`inline text<target>`

Note

There is no space between “inline text” and the angle bracket that immediately follows it. This is precisely the opposite of the convention for inline text that links to a location outside of the Ceph documentation. If this seems inconsistent and confusing to you, then you’re right. It is inconsistent and confusing.

Escaping Bold Characters within Words

This section explains how to make certain letters within a word bold while leaving the other letters in the word regular (non-bold).

The following single-line paragraph provides an example of this:

Ceph File System.

In ReStructured Text, the following formula will not work:

**C**eph **F**ile **S**ystem

The bolded notation must be turned off by means of the escape character (\), as shown here:

**C**\eph **F**\ile **S**\ystem

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profit Ceph Foundation. If you would like to support this and our other efforts, please consider joining now.