5 The **easiest way** to help the Ceph project is to contribute to the
6 documentation. As the Ceph user base grows and the development pace quickens, an
7 increasing number of people are updating the documentation and adding new
8 information. Even small contributions like fixing spelling errors or clarifying
9 instructions will help the Ceph project immensely.
11 The Ceph documentation source resides in the ``ceph/doc`` directory of the Ceph
12 repository, and Python Sphinx renders the source into HTML and manpages. The
13 http://ceph.com/docs link currently displays the ``master`` branch by default,
14 but you may view documentation for older branches (e.g., ``argonaut``) or future
15 branches (e.g., ``next``) as well as work-in-progress branches by substituting
16 ``master`` with the branch name you prefer.
22 Making a documentation contribution generally involves the same procedural
23 sequence as making a code contribution, except that you must build documentation
24 source instead of compiling program source. The sequence includes the following
30 #. `Build the Source`_
31 #. `Commit the Change`_
33 #. `Make a Pull Request`_
39 Ceph documentation lives in the Ceph repository right alongside the Ceph source
40 code under the ``ceph/doc`` directory. For details on github and Ceph,
41 see :ref:`Get Involved`.
43 The most common way to make contributions is to use the `Fork and Pull`_
46 #. Install git locally. For Debian/Ubuntu, execute:
50 sudo apt-get install git
58 For CentOS/RHEL, execute:
64 #. Ensure your ``.gitconfig`` file has your name and email address. :
69 email = {your-email-address}
76 git config --global user.name "John Doe"
77 git config --global user.email johndoe@example.com
80 #. Create a `github`_ account (if you don't have one).
82 #. Fork the Ceph project. See https://github.com/ceph/ceph.
84 #. Clone your fork of the Ceph project to your local host.
87 Ceph organizes documentation into an information architecture primarily by its
90 - **Ceph Storage Cluster:** The Ceph Storage Cluster documentation resides
91 under the ``doc/rados`` directory.
93 - **Ceph Block Device:** The Ceph Block Device documentation resides under
94 the ``doc/rbd`` directory.
96 - **Ceph Object Storage:** The Ceph Object Storage documentation resides under
97 the ``doc/radosgw`` directory.
99 - **Ceph File System:** The Ceph File System documentation resides under the
100 ``doc/cephfs`` directory.
102 - **Installation (Quick):** Quick start documentation resides under the
103 ``doc/start`` directory.
105 - **Installation (Manual):** Manual installation documentation resides under
106 the ``doc/install`` directory.
108 - **Manpage:** Manpage source resides under the ``doc/man`` directory.
110 - **Developer:** Developer documentation resides under the ``doc/dev``
113 - **Images:** If you include images such as JPEG or PNG files, you should
114 store them under the ``doc/images`` directory.
120 When you make small changes to the documentation, such as fixing typographical
121 errors or clarifying explanations, use the ``master`` branch (default). You
122 should also use the ``master`` branch when making contributions to features that
123 are in the current release. ``master`` is the most commonly used branch. :
129 When you make changes to documentation that affect an upcoming release, use
130 the ``next`` branch. ``next`` is the second most commonly used branch. :
136 When you are making substantial contributions such as new features that are not
137 yet in the current release; if your contribution is related to an issue with a
138 tracker ID; or, if you want to see your documentation rendered on the Ceph.com
139 website before it gets merged into the ``master`` branch, you should create a
140 branch. To distinguish branches that include only documentation updates, we
141 prepend them with ``wip-doc`` by convention, following the form
142 ``wip-doc-{your-branch-name}``. If the branch relates to an issue filed in
143 http://tracker.ceph.com/issues, the branch name incorporates the issue number.
144 For example, if a documentation branch is a fix for issue #4000, the branch name
145 should be ``wip-doc-4000`` by convention and the relevant tracker URL will be
146 http://tracker.ceph.com/issues/4000.
148 .. note:: Please do not mingle documentation contributions and source code
149 contributions in a single commit. When you keep documentation
150 commits separate from source code commits, it simplifies the review
151 process. We highly recommend that any pull request that adds a feature or
152 a configuration option, should also include a documentation commit,
153 describing the relevant changes/options.
155 Before you create your branch name, ensure that it doesn't already exist in the
156 local or remote repository. :
160 git branch -a | grep wip-doc-{your-branch-name}
162 If it doesn't exist, create your branch:
166 git checkout -b wip-doc-{your-branch-name}
172 Modifying a document involves opening a reStructuredText file, changing
173 its contents, and saving the changes. See `Documentation Style Guide`_ for
174 details on syntax requirements.
176 Adding a document involves creating a new reStructuredText file within the
177 ``doc`` directory tree with a ``*.rst``
178 extension. You must also include a reference to the document: a hyperlink
179 or a table of contents entry. The ``index.rst`` file of a top-level directory
180 usually contains a TOC, where you can add the new file name. All documents must
181 have a title. See `Headings`_ for details.
183 Your new document doesn't get tracked by ``git`` automatically. When you want
184 to add the document to the repository, you must use ``git add
185 {path-to-filename}``. For example, from the top level directory of the
186 repository, adding an ``example.rst`` file to the ``rados`` subdirectory would
191 git add doc/rados/example.rst
193 Deleting a document involves removing it from the repository with ``git rm
194 {path-to-filename}``. For example:
198 git rm doc/rados/example.rst
200 You must also remove any reference to a deleted document from other documents.
206 To build the documentation, navigate to the ``ceph`` repository directory:
214 The directory that contains ``build-doc`` and ``serve-doc`` must be included
215 in the ``PATH`` environment variable in order for these commands to work.
218 To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute:
224 To scan for the reachability of external links, execute:
228 admin/build-doc linkcheck
230 Executing ``admin/build-doc`` will create a ``build-doc`` directory under
231 ``ceph``. You may need to create a directory under ``ceph/build-doc`` for
232 output of Javadoc files:
236 mkdir -p output/html/api/libcephfs-java/javadoc
238 The build script ``build-doc`` will produce an output of errors and warnings.
239 You MUST fix errors in documents you modified before committing a change, and
240 you SHOULD fix warnings that are related to syntax you modified.
242 .. important:: You must validate ALL HYPERLINKS. If a hyperlink is broken,
243 it automatically breaks the build!
245 Once you build the documentation set, you may start an HTTP server at
246 ``http://localhost:8080/`` to view it:
252 You can also navigate to ``build-doc/output`` to inspect the built documents.
253 There should be an ``html`` directory and a ``man`` directory containing
254 documentation in HTML and manpage formats respectively.
256 Build the Source (First Time)
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259 Ceph uses Python Sphinx, which is generally distribution agnostic. The first
260 time you build Ceph documentation, it will generate a doxygen XML tree, which
261 is a bit time consuming.
263 Python Sphinx does have some dependencies that vary across distributions. The
264 first time you build the documentation, the script will notify you if you do not
265 have the dependencies installed. To run Sphinx and build documentation successfully,
266 the following packages are required:
270 <style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style>
271 <table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3>
287 </td><td><h3>Fedora</h3>
306 </td><td><h3>CentOS/RHEL</h3>
324 </td></tr></tbody></table>
327 Install each dependency that is not installed on your host. For Debian/Ubuntu
328 distributions, execute the following:
332 sudo apt-get install gcc python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen graphviz ant ditaa
333 sudo apt-get install python-sphinx
335 For Fedora distributions, execute the following:
339 sudo yum install gcc python-devel python-pip python-virtualenv libxml2-devel libxslt-devel doxygen graphviz ant
340 sudo pip install html2text
341 sudo yum install python-jinja2 python-pygments python-docutils python-sphinx
342 sudo yum install jericho-html ditaa
344 For CentOS/RHEL distributions, it is recommended to have ``epel`` (Extra
345 Packages for Enterprise Linux) repository as it provides some extra packages
346 which are not available in the default repository. To install ``epel``, execute
351 sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
353 For CentOS/RHEL distributions, execute the following:
357 sudo yum install gcc python-devel python-pip python-virtualenv libxml2-devel libxslt-devel doxygen graphviz ant
358 sudo pip install html2text
360 For CentOS/RHEL distributions, the remaining python packages are not available
361 in the default and ``epel`` repositories. So, use http://rpmfind.net/ to find
362 the packages. Then, download them from a mirror and install them. For example:
366 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm
367 sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm
368 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm
369 sudo yum install python-pygments-1.4-9.el7.noarch.rpm
370 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
371 sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm
372 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm
373 sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm
375 Ceph documentation makes extensive use of `ditaa`_, which is not presently built
376 for CentOS/RHEL7. You must install ``ditaa`` if you are making changes to
377 ``ditaa`` diagrams so that you can verify that they render properly before you
378 commit new or modified ``ditaa`` diagrams. You may retrieve compatible required
379 packages for CentOS/RHEL distributions and install them manually. To run
380 ``ditaa`` on CentOS/RHEL7, following dependencies are required:
386 Use http://rpmfind.net/ to find compatible ``ditaa`` and the dependencies.
387 Then, download them from a mirror and install them. For example:
391 wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm
392 sudo yum install jericho-html-3.3-4.fc22.noarch.rpm
393 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
394 sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm
395 wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm
396 sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm
397 wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm
398 sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm
400 Once you have installed all these packages, build the documentation by following
401 the steps given in `Build the Source`_.
407 Ceph documentation commits are simple, but follow a strict convention:
409 - A commit SHOULD have 1 file per commit (it simplifies rollback). You MAY
410 commit multiple files with related changes. Unrelated changes SHOULD NOT
411 be put into the same commit.
412 - A commit MUST have a comment.
413 - A commit comment MUST be prepended with ``doc:``. (strict)
414 - The comment summary MUST be one line only. (strict)
415 - Additional comments MAY follow a blank line after the summary,
417 - A commit MAY include ``Fixes: #{bug number}``.
418 - Commits MUST include ``Signed-off-by: Firstname Lastname <email>``. (strict)
420 .. tip:: Follow the foregoing convention particularly where it says
421 ``(strict)`` or you will be asked to modify your commit to comply with
424 The following is a common commit comment (preferred)::
426 doc: Fixes a spelling error and a broken hyperlink.
428 Signed-off-by: John Doe <john.doe@gmail.com>
431 The following comment includes a reference to a bug. ::
433 doc: Fixes a spelling error and a broken hyperlink.
437 Signed-off-by: John Doe <john.doe@gmail.com>
440 The following comment includes a terse sentence following the comment summary.
441 There is a carriage return between the summary line and the description::
443 doc: Added mon setting to monitor config reference
445 Describes 'mon setting', which is a new setting added
448 Signed-off-by: John Doe <john.doe@gmail.com>
451 To commit changes, execute the following:
458 An easy way to manage your documentation commits is to use visual tools for
459 ``git``. For example, ``gitk`` provides a graphical interface for viewing the
460 repository history, and ``git-gui`` provides a graphical interface for viewing
461 your uncommitted changes, staging them for commit, committing the changes and
462 pushing them to your forked Ceph repository.
465 For Debian/Ubuntu, execute:
469 sudo apt-get install gitk git-gui
471 For Fedora/CentOS/RHEL, execute:
475 sudo yum install gitk git-gui
481 cd {git-ceph-repo-path}
484 Finally, select **File->Start git gui** to activate the graphical user interface.
490 Once you have one or more commits, you must push them from the local copy of the
491 repository to ``github``. A graphical tool like ``git-gui`` provides a user
492 interface for pushing to the repository. If you created a branch previously:
496 git push origin wip-doc-{your-branch-name}
508 As noted earlier, you can make documentation contributions using the `Fork and
516 After you make a pull request, please email ceph-docs@redhat.com.
520 Documentation Style Guide
521 =========================
523 One objective of the Ceph documentation project is to ensure the readability of
524 the documentation in both native restructuredText format and its rendered
525 formats such as HTML. Navigate to your Ceph repository and view a document in
526 its native format. You may notice that it is generally as legible in a terminal
527 as it is in its rendered HTML format. Additionally, you may also notice that
528 diagrams in ``ditaa`` format also render reasonably well in text mode. :
532 less doc/architecture.rst
534 Review the following style guides to maintain this consistency.
540 #. **Document Titles:** Document titles use the ``=`` character overline and
541 underline with a leading and trailing space on the title text line.
542 See `Document Title`_ for details.
544 #. **Section Titles:** Section tiles use the ``=`` character underline with no
545 leading or trailing spaces for text. Two carriage returns should precede a
546 section title (unless an inline reference precedes it). See `Sections`_ for
549 #. **Subsection Titles:** Subsection titles use the ``_`` character underline
550 with no leading or trailing spaces for text. Two carriage returns should
551 precede a subsection title (unless an inline reference precedes it).
557 As a general rule, we prefer text to wrap at column 80 so that it is legible in
558 a command line interface without leading or trailing white space. Where
559 possible, we prefer to maintain this convention with text, lists, literal text
560 (exceptions allowed), tables, and ``ditaa`` graphics.
562 #. **Paragraphs**: Paragraphs have a leading and a trailing carriage return,
563 and should be 80 characters wide or less so that the documentation can be
564 read in native format in a command line terminal.
566 #. **Literal Text:** To create an example of literal text (e.g., command line
567 usage), terminate the preceding paragraph with ``::`` or enter a carriage
568 return to create an empty line after the preceding paragraph; then, enter
569 ``::`` on a separate line followed by another empty line. Then, begin the
570 literal text with tab indentation (preferred) or space indentation of 3
573 #. **Indented Text:** Indented text such as bullet points
574 (e.g., ``- some text``) may span multiple lines. The text of subsequent
575 lines should begin at the same character position as the text of the
576 indented text (less numbers, bullets, etc.).
578 Indented text may include literal text examples. Whereas, text indentation
579 should be done with spaces, literal text examples should be indented with
580 tabs. This convention enables you to add an additional indented paragraph
581 following a literal example by leaving a blank line and beginning the
582 subsequent paragraph with space indentation.
584 #. **Numbered Lists:** Numbered lists should use autonumbering by starting
585 a numbered indent with ``#.`` instead of the actual number so that
586 numbered paragraphs can be repositioned without requiring manual
589 #. **Code Examples:** Ceph supports the use of the
590 ``.. code-block::<language>`` role, so that you can add highlighting to
591 source examples. This is preferred for source code. However, use of this
592 tag will cause autonumbering to restart at 1 if it is used as an example
593 within a numbered list. See `Showing code examples`_ for details.
596 Paragraph Level Markup
597 ----------------------
599 The Ceph project uses `paragraph level markup`_ to highlight points.
601 #. **Tip:** Use the ``.. tip::`` directive to provide additional information
602 that assists the reader or steers the reader away from trouble.
604 #. **Note**: Use the ``.. note::`` directive to highlight an important point.
606 #. **Important:** Use the ``.. important::`` directive to highlight important
607 requirements or caveats (e.g., anything that could lead to data loss). Use
608 this directive sparingly, because it renders in red.
610 #. **Version Added:** Use the ``.. versionadded::`` directive for new features
611 or configuration settings so that users know the minimum release for using
614 #. **Version Changed:** Use the ``.. versionchanged::`` directive for changes
615 in usage or configuration settings.
617 #. **Deprecated:** Use the ``.. deprecated::`` directive when CLI usage,
618 a feature or a configuration setting is no longer preferred or will be
621 #. **Topic:** Use the ``.. topic::`` directive to encapsulate text that is
622 outside the main flow of the document. See the `topic directive`_ for
629 All documents must be linked from another document or a table of contents,
630 otherwise you will receive a warning when building the documentation.
632 The Ceph project uses the ``.. toctree::`` directive. See `The TOC tree`_
633 for details. When rendering a TOC, consider specifying the ``:maxdepth:``
634 parameter so the rendered TOC is reasonably terse.
636 Document authors should prefer to use the ``:ref:`` syntax where a link target
637 contains a specific unique identifier (e.g., ``.. _unique-target-id:``), and a
638 reference to the target specifically references the target (e.g.,
639 ``:ref:`unique-target-id```) so that if source files are moved or the
640 information architecture changes, the links will still work. See
641 `Cross referencing arbitrary locations`_ for details.
643 Ceph documentation also uses the backtick (accent grave) character followed by
644 the link text, another backtick and an underscore. Sphinx allows you to
645 incorporate the link destination inline; however, we prefer to use the use the
646 ``.. _Link Text: ../path`` convention at the bottom of the document, because it
647 improves the readability of the document in a command line interface.
650 .. _Python Sphinx: http://sphinx-doc.org
651 .. _resturcturedText: http://docutils.sourceforge.net/rst.html
652 .. _Fork and Pull: https://help.github.com/articles/using-pull-requests
653 .. _github: http://github.com
654 .. _ditaa: http://ditaa.sourceforge.net/
655 .. _Document Title: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle
656 .. _Sections: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections
657 .. _Cross referencing arbitrary locations: http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
658 .. _The TOC tree: http://sphinx-doc.org/markup/toctree.html
659 .. _Showing code examples: http://sphinx-doc.org/markup/code.html
660 .. _paragraph level markup: http://sphinx-doc.org/markup/para.html
661 .. _topic directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic