RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2024-12-30 15:33:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1310 from ceph/wip-doc-documenting-ceph

Browse Source 
Wip doc documenting ceph

Reviewed-by: Sage Weil <sage@inktank.com>
This commit is contained in:
Sage Weil 2014-03-10 16:13:08 -07:00
commit ccf9a7459c
2 changed files with 450 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

448
doc/start/documenting-ceph.rst Normal file
View File

@ -0,0 +1,448 @@
==================
Documenting Ceph
==================
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.
Making Contributions
====================
Making a documentation contribution generally involves the same procedural
sequence as making a code contribution, except that you must build documentation
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
--------------
Ceph documentation lives in the Ceph repository right along side the Ceph source
code under the ``ceph/doc`` directory. The most common way to make contributions
is to use the `Fork and Pull`_ approach. To use this approach, you must:
- Install git locally. ::
sudo apt-get install git
- Ensure your ``.gitconfig`` file has your name and email address. ::
[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.
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.
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
When you make changes to documentation that affect an upcoming release, use
the ``next`` branch. ``next`` is the second most commonly used branch. ::
git checkout next
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.
.. 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.
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
-------------
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::
git rm doc/rados/example.rst
You must also remove any reference to the document from other documents.
Build the Source
----------------
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
distributions, execute the following::
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.
Commit the Change
-----------------
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:
- 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.
- A commit MUST have a comment.
- A commit comment MUST be prepended with ``doc:``. (strict)
- The comment summary MUST be one line only. (strict)
- Additional comments MAY follow a blank line after the summary,
but should be terse.
- A commit MAY include ``Fixes: #{bug number}``.
- 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: Fixes 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: Fixes a spelling error and a broken hyperlink.
Fixes: #1234
Signed-off-by: John Doe <john.doe@gmail.com>
The following comment includes a terse sentence following the comment summary.
There is a carriage return between the summary line and the description::
doc: Added mon setting to monitor config reference
Describes 'mon setting', which is a new setting added
to config_opts.h.
Signed-off-by: John Doe <john.doe@gmail.com>
To commit changes, execute the following::
git commit -a
You can also a graphical editor like ``gitk`` and ``git-gui``. ::
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
---------------
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. ::
git push
Make a Pull Request
-------------------
As noted earlier, you can make documentation contributions using the `Fork and
Pull`_ approach.
Notify the Relevant Person
--------------------------
After you make a pull request, notify the relevant person. For general
documentation pull requests, notify `John Wilkins`_.
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. ::
cat doc/architecture.rst | less
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 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
---------
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.
#. **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. 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.
#. **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.
TOC and Hyperlinks
------------------
All documents must be linked from another document or a table of contents,
otherwise you will receive a warning when building the documentation.
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.
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.
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.
.. _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
.. _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
.. _topic directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic
.. _John Wilkins: mailto:john.wilkins@inktank.com

2
doc/start/intro.rst
View File

@ -62,8 +62,10 @@ recommendations and operating system recommendations.
code or bugs by getting involved in the Ceph community.
.. toctree::
:maxdepth: 2
get-involved
documenting-ceph
.. raw:: html