.. _documenting_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 :ref:`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 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 :ref:`Get Involved`. 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: .. prompt:: bash $ sudo apt-get install git In Fedora, run the following command: .. prompt:: bash $ sudo yum install git In CentOS/RHEL, run the following command: .. prompt:: bash $ sudo yum install git #. Make sure that your ``.gitconfig`` file has been configured to include your name and email address: .. code-block:: ini [user] email = {your-email-address} name = {your-name} For example: .. prompt:: bash $ 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. .. prompt:: bash $ git branch -a | grep wip-doc-{your-branch-name} If it doesn't exist, create your branch: .. prompt:: bash $ 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: .. prompt:: bash $ git add doc/rados/example.rst Deleting a document involves removing it from the repository with ``git rm {path-to-filename}``. For example: .. prompt:: bash $ 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: .. prompt:: bash $ 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: .. prompt:: bash $ admin/build-doc To scan for the reachability of external links, execute: .. prompt:: bash $ 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: .. prompt:: bash $ 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: .. prompt:: bash $ 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: .. raw:: html

Debian/Ubuntu

- gcc - python3-dev - python3-pip - python3-sphinx - python3-venv - libxml2-dev - libxslt1-dev - doxygen - graphviz - ant - ditaa - cython3 .. raw:: html

Fedora

- gcc - python-devel - python-pip - python-docutils - python-jinja2 - python-pygments - python-sphinx - libxml2-devel - libxslt1-devel - doxygen - graphviz - ant - ditaa .. raw:: html

CentOS/RHEL

- gcc - python-devel - python-pip - python-docutils - python-jinja2 - python-pygments - python-sphinx - libxml2-dev - libxslt1-dev - doxygen - graphviz - ant .. raw:: html
Install each dependency that is not installed on your host. For Debian/Ubuntu distributions, run the following commands: .. prompt:: bash $ 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: .. prompt:: bash $ 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: .. prompt:: bash $ sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm For CentOS/RHEL distributions, run the following commands: .. prompt:: bash $ 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: .. prompt:: bash $ 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: .. prompt:: bash $ 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 ``. (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 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 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 To commit changes, execute the following: .. prompt:: bash $ 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: .. prompt:: bash $ sudo apt-get install gitk git-gui For Fedora/CentOS/RHEL, execute: .. prompt:: bash $ sudo yum install gitk git-gui Then, execute: .. prompt:: bash $ 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: .. prompt:: bash $ git push origin wip-doc-{your-branch-name} Otherwise: .. prompt:: bash $ 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. A. Make the first commit. :: doc/glossary: improve "CephX" entry Improve the glossary entry for "CephX". Signed-off-by: Zac Dover # 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 # B. 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 # 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 C. 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 # 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. A. Run the command ``git rebase -i main``, which rebases the current branch (the feature branch) against the ``main`` branch: .. prompt:: bash git rebase -i main B. 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 = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup [-C | -c] = 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 = run command (the rest of the line) using shell # b, break = stop here (continue rebase later with 'git rebase --continue') # d, drop = remove commit # l, label