2014-01-21 22:18:55 +00:00
|
|
|
==================
|
|
|
|
Documenting Ceph
|
|
|
|
==================
|
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
The **easiest way** to help the Ceph project is to contribute to the
|
|
|
|
documentation. As the Ceph user base grows and the development pace quickens, an
|
|
|
|
increasing number of people are updating the documentation and adding new
|
|
|
|
information. Even small contributions like fixing spelling errors or clarifying
|
|
|
|
instructions help the Ceph project immensely.
|
|
|
|
|
|
|
|
When you view Ceph documentation online, the primary link is
|
|
|
|
http://ceph.com/docs/master. The documentation source in the ``ceph/docs``
|
|
|
|
directory gets rendered to HTML and presented online. The ``master`` portion of
|
|
|
|
the path reflects the branch name, which means you can view documentation for
|
|
|
|
older branches (e.g., ``argonaut``) or future branches (e.g., ``next``) as well
|
|
|
|
as work-in-progress branches.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
|
|
|
Making Contributions
|
|
|
|
====================
|
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
Making a documentation contribution generally involves the same procedural
|
2014-01-21 22:18:55 +00:00
|
|
|
sequence as making a code contribution, except that you must build documentation
|
2014-02-01 05:58:23 +00:00
|
|
|
source instead of compiling program source. The 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 the Relevant Person`_
|
|
|
|
|
|
|
|
Get the Source
|
|
|
|
--------------
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
Ceph documentation lives in the Ceph repository right along side the Ceph source
|
2014-05-01 04:31:06 +00:00
|
|
|
code under the ``ceph/doc`` directory. For details on github and ceph,
|
|
|
|
see :ref:`Get Involved`.
|
|
|
|
|
|
|
|
The most common way to make contributions
|
2014-02-01 05:58:23 +00:00
|
|
|
is to use the `Fork and Pull`_ approach. To use this approach, you must:
|
|
|
|
|
|
|
|
- Install git locally. ::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
sudo apt-get install git
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
- Ensure your ``.gitconfig`` file has your name and email address. ::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
[user]
|
|
|
|
email = {your-email-address}
|
|
|
|
name = {your-name}
|
|
|
|
|
|
|
|
- Create a `github`_ account (if you don't have one).
|
|
|
|
|
|
|
|
- Fork the Ceph project.
|
|
|
|
|
|
|
|
- Clone your forked project.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
All Ceph documentation resides under the ``ceph/doc`` directory and
|
|
|
|
subdirectories of the Ceph repository. Ceph organizes documentation into an
|
|
|
|
information architecture primarily by its main components.
|
|
|
|
|
|
|
|
- **Ceph Storage Cluster:** The Ceph Storage Cluster documentation resides
|
|
|
|
under the ``doc/rados`` directory.
|
|
|
|
|
|
|
|
- **Ceph Block Device:** The Ceph Block Device documentation resides under
|
|
|
|
the ``doc/rbd`` directory.
|
|
|
|
|
|
|
|
- **Ceph Object Storage:** The Ceph Object Storage documentation resides under
|
|
|
|
the ``doc/radosgw`` directory.
|
|
|
|
|
|
|
|
- **Ceph Filesystem:** The Ceph Filesystem documentation resides under the
|
|
|
|
``doc/cephfs`` directory.
|
|
|
|
|
|
|
|
- **Installation (Quick):** Quick start documentation resides under the
|
|
|
|
``doc/start`` directory.
|
|
|
|
|
|
|
|
- **Installation (Manual):** Manual installation documentation resides under
|
|
|
|
the ``doc/install`` directory.
|
|
|
|
|
|
|
|
- **Manpage:** Manpage source resides under the ``doc/man`` directory.
|
|
|
|
|
|
|
|
- **Developer:** Developer documentation resides under the ``doc/dev``
|
|
|
|
directory.
|
|
|
|
|
|
|
|
- **Images:** If you include images such as JPEG or PNG files, you should
|
|
|
|
store them under the ``doc/images`` directory.
|
|
|
|
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
Select a Branch
|
|
|
|
---------------
|
|
|
|
|
|
|
|
When you make small changes to the documentation, such as fixing typographical
|
|
|
|
errors or clarifying explanations, use the ``master`` branch (default). You
|
|
|
|
should also use the ``master`` branch when making contributions to features that
|
|
|
|
are in the current release. ``master`` is the most commonly used branch. ::
|
|
|
|
|
|
|
|
git checkout master
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
When you make changes to documentation that affect an upcoming release, use
|
|
|
|
the ``next`` branch. ``next`` is the second most commonly used branch. ::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
git checkout next
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
When you are making substantial contributions such as new features that are not
|
|
|
|
yet in the current release; if your contribution is related to an issue with a
|
|
|
|
tracker ID; or, if you want to see your documentation rendered on the Ceph.com
|
|
|
|
website before it gets merged into the ``master`` branch, you should create a
|
|
|
|
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.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
.. note:: Please don't commingle documentation contributions and source code
|
|
|
|
contributions in a single pull request. Editors review the documentation
|
|
|
|
and engineers review source code changes. When you keep documentation
|
|
|
|
pull requests separate from source code pull requests, it simplifies the
|
|
|
|
process and we won't have to ask you to resubmit the requests separately.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
Before you create your branch name, 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
|
|
|
|
-------------
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
Modifying a document simply 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 under the
|
|
|
|
``doc`` directory or its subdirectories and saving the file with a ``*.rst``
|
|
|
|
file 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::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
git rm doc/rados/example.rst
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
You must also remove any reference to the document from other documents.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
Build the Source
|
|
|
|
----------------
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
To build the documentation, navigate to the ``ceph`` repository directory;
|
|
|
|
then execute the build script::
|
|
|
|
|
|
|
|
cd ceph
|
|
|
|
admin/build-doc
|
|
|
|
|
|
|
|
The build script will produce an output of errors and warnings. You MUST
|
|
|
|
fix errors before committing a change, and you SHOULD fix warnings.
|
|
|
|
|
|
|
|
.. important:: You must validate ALL HYPERLINKS. If a hyperlink is broken,
|
|
|
|
it automatically breaks the build!
|
|
|
|
|
|
|
|
The first time you build the documentation, the script will notify you if
|
|
|
|
you do not have the dependencies installed. To run Sphinx, at least
|
|
|
|
the following are required:
|
|
|
|
|
|
|
|
- python-dev
|
|
|
|
- python-pip
|
|
|
|
- python-virtualenv
|
|
|
|
- libxml2-dev
|
|
|
|
- libxslt-dev
|
|
|
|
- doxygen
|
|
|
|
- ditaa
|
|
|
|
- graphviz
|
|
|
|
|
|
|
|
Install each dependency that isn't installed on your host. For Debian/Ubuntu
|
2014-01-23 22:27:33 +00:00
|
|
|
distributions, execute the following::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
sudo apt-get install python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen ditaa graphviz ant
|
|
|
|
|
|
|
|
.. For CentOS/RHEL distributions, execute the following::
|
|
|
|
|
|
|
|
.. sudo yum install python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen ditaa graphviz ant
|
|
|
|
|
|
|
|
|
|
|
|
Once you build the documentation set, you may navigate to the source directory
|
|
|
|
to view it::
|
|
|
|
|
|
|
|
cd build-doc/output
|
|
|
|
|
|
|
|
There should be an ``html`` directory and a ``man`` directory containing
|
|
|
|
documentation in HTML and manpage formats respectively.
|
|
|
|
|
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
Commit the Change
|
|
|
|
-----------------
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
Ceph documentation commits are simple, but follow a strict convention:
|
|
|
|
|
2014-03-10 18:58:53 +00:00
|
|
|
- A commit SHOULD have 1 file per commit (it simplifies rollback). You MAY
|
|
|
|
commit multiple files with related changes. Unrelated changes SHOULD NOT
|
|
|
|
be put into the same commit.
|
2014-01-23 22:27:33 +00:00
|
|
|
- A commit MUST have a comment.
|
|
|
|
- A commit comment MUST be prepended with ``doc:``. (strict)
|
2014-01-21 22:18:55 +00:00
|
|
|
- The comment summary MUST be one line only. (strict)
|
|
|
|
- Additional comments MAY follow a blank line after the summary,
|
|
|
|
but should be terse.
|
2014-03-10 22:58:57 +00:00
|
|
|
- A commit MAY include ``Fixes: #{bug number}``.
|
|
|
|
- Commits MUST include ``Signed-off-by: Firstname Lastname <email>``. (strict)
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
.. tip:: Follow the foregoing convention particularly where it says
|
|
|
|
``(strict)`` or you will be asked to modify your commit to comply with
|
|
|
|
this convention.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
The following is a common commit comment (preferred)::
|
|
|
|
|
|
|
|
doc: Fixes a spelling error and a broken hyperlink.
|
|
|
|
|
2014-03-10 22:58:57 +00:00
|
|
|
Signed-off-by: John Doe <john.doe@gmail.com>
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
|
|
|
The following comment includes a reference to a bug. ::
|
|
|
|
|
|
|
|
doc: Fixes a spelling error and a broken hyperlink.
|
|
|
|
|
2014-03-10 22:58:57 +00:00
|
|
|
Fixes: #1234
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-03-10 22:58:57 +00:00
|
|
|
Signed-off-by: John Doe <john.doe@gmail.com>
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
The following comment includes a terse sentence following the comment summary.
|
|
|
|
There is a carriage return between the summary line and the description::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
doc: Added mon setting to monitor config reference
|
|
|
|
|
|
|
|
Describes 'mon setting', which is a new setting added
|
|
|
|
to config_opts.h.
|
|
|
|
|
2014-03-10 22:58:57 +00:00
|
|
|
Signed-off-by: John Doe <john.doe@gmail.com>
|
2014-02-01 05:58:23 +00:00
|
|
|
|
|
|
|
|
|
|
|
To commit changes, execute the following::
|
|
|
|
|
|
|
|
git commit -a
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
You can also a graphical editor like ``gitk`` and ``git-gui``. ::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
sudo apt-get install gitk git-gui
|
|
|
|
cd {git-ceph-repo-path}
|
|
|
|
gitk
|
|
|
|
|
|
|
|
Then select **File->Start git gui** to activate the graphical user interface.
|
|
|
|
|
|
|
|
|
|
|
|
Push the Change
|
2014-01-21 22:18:55 +00:00
|
|
|
---------------
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
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. ::
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
git push
|
|
|
|
|
|
|
|
|
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
Make a Pull Request
|
|
|
|
-------------------
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
As noted earlier, you can make documentation contributions using the `Fork and
|
|
|
|
Pull`_ approach.
|
|
|
|
|
|
|
|
|
|
|
|
|
2014-02-01 05:58:23 +00:00
|
|
|
Notify the Relevant Person
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
After you make a pull request, notify the relevant person. For general
|
|
|
|
documentation pull requests, notify `John Wilkins`_.
|
|
|
|
|
|
|
|
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
Documentation Style Guide
|
|
|
|
=========================
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
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. ::
|
|
|
|
|
|
|
|
cat doc/architecture.rst | less
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
Review the following style guides to maintain this consistency.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
|
|
|
Headings
|
|
|
|
--------
|
|
|
|
|
|
|
|
#. **Document Titles:** Document titles use the ``=`` character overline and
|
2014-01-23 22:27:33 +00:00
|
|
|
underline with a leading and trailing space on the title text line.
|
|
|
|
See `Document Title`_ for details.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
#. **Section Titles:** Section tiles 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
|
|
|
|
---------
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
As a general rule, we prefer text to wrap at column 80 so that it is legible in
|
|
|
|
a command line interface without leading or trailing white space. Where
|
|
|
|
possible, we prefer to maintain this convention with text, lists, literal text
|
|
|
|
(exceptions allowed), tables, and ``ditaa`` graphics.
|
|
|
|
|
2014-01-21 22:18:55 +00:00
|
|
|
#. **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.
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **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.).
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
Indented text may include literal text examples. Whereas, 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.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **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.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **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.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
Paragraph Level Markup
|
|
|
|
----------------------
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
The Ceph project uses `paragraph level markup`_ to highlight points.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **Tip:** Use the ``.. tip::`` directive to provide additional information
|
|
|
|
that assists the reader or steers the reader away from trouble.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **Note**: Use the ``.. note::`` directive to highlight an important point.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **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.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **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.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **Deprecated:** Use the ``.. deprecated::`` directive when CLI usage,
|
|
|
|
a feature or a configuration setting is no longer preferred or will be
|
|
|
|
discontinued.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
#. **Topic:** Use the ``.. topic::`` directive to encapsulate text that is
|
|
|
|
outside the main flow of the document. See the `topic directive`_ for
|
|
|
|
additional details.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
TOC and Hyperlinks
|
|
|
|
------------------
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
All documents must be linked from another document or a table of contents,
|
|
|
|
otherwise you will receive a warning when building the documentation.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
The Ceph project uses the ``.. toctree::`` directive. See `The TOC tree`_
|
|
|
|
for details. When rendering a TOC, consider specifying the ``:maxdepth:``
|
|
|
|
parameter so the rendered TOC is reasonably terse.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
Document authors should prefer to use the ``:ref:`` syntax where a link target
|
|
|
|
contains a specific unique identifier (e.g., ``.. _unique-target-id:``), and a
|
|
|
|
reference to the target specifically references the target (e.g.,
|
|
|
|
``:ref:`unique-target-id```) so that if source files are moved or the
|
|
|
|
information architecture changes, the links will still work. See
|
|
|
|
`Cross referencing arbitrary locations`_ for details.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
2014-01-23 22:27:33 +00:00
|
|
|
Ceph documentation also uses the backtick (accent grave) character followed by
|
|
|
|
the link text, another backtick and an underscore. Sphinx allows you to
|
|
|
|
incorporate the link destination inline; however, we prefer to use the use the
|
|
|
|
``.. _Link Text: ../path`` convention at the bottom of the document, because it
|
|
|
|
improves the readability of the document in a command line interface.
|
2014-01-21 22:18:55 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _Python Sphinx: http://sphinx-doc.org
|
|
|
|
.. _resturcturedText: http://docutils.sourceforge.net/rst.html
|
|
|
|
.. _Fork and Pull: https://help.github.com/articles/using-pull-requests
|
|
|
|
.. _github: http://github.com
|
|
|
|
.. _Document Title: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle
|
2014-01-23 22:27:33 +00:00
|
|
|
.. _Sections: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections
|
|
|
|
.. _Cross referencing arbitrary locations: http://sphinx-doc.org/markup/inline.html#ref-role
|
|
|
|
.. _The TOC tree: http://sphinx-doc.org/markup/toctree.html
|
|
|
|
.. _Showing code examples: http://sphinx-doc.org/markup/code.html
|
|
|
|
.. _paragraph level markup: http://sphinx-doc.org/markup/para.html
|
2014-02-01 05:58:23 +00:00
|
|
|
.. _topic directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic
|
2014-03-10 18:58:53 +00:00
|
|
|
.. _John Wilkins: mailto:john.wilkins@inktank.com
|