mirror of
https://github.com/ceph/ceph
synced 2025-01-01 08:32:24 +00:00
Merge pull request #2389 from ceph/wip-doc-documenting-ceph
doc: Update documenting ceph to include CentOS/RHEL Reviewed-by: John Wilkins <jowilkin@redhat.com>
This commit is contained in:
John Wilkins
commit
bec99559f3
@ -6,14 +6,14 @@ 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.
|
||||
instructions will 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.
|
||||
The Ceph documentation source resides in the ``ceph/docs`` directory of the Ceph
|
||||
repository, and Python Sphinx renders the source into HTML and manpages. The
|
||||
http://ceph.com/docs link currenly displays the ``master`` branch by default,
|
||||
but you may view documentation for older branches (e.g., ``argonaut``) or future
|
||||
branches (e.g., ``next``) as well as work-in-progress branches by substituting
|
||||
``master`` with the branch name you prefer.
|
||||
|
||||
|
||||
Making Contributions
|
||||
@ -37,31 +37,45 @@ Get the Source
|
||||
--------------
|
||||
|
||||
Ceph documentation lives in the Ceph repository right alongside the Ceph source
|
||||
code under the ``ceph/doc`` directory. For details on github and ceph,
|
||||
code under the ``ceph/doc`` directory. For details on github and Ceph,
|
||||
see :ref:`Get Involved`.
|
||||
|
||||
The most common way to make contributions
|
||||
is to use the `Fork and Pull`_ approach. To use this approach, you must:
|
||||
The most common way to make contributions is to use the `Fork and Pull`_
|
||||
approach. You must:
|
||||
|
||||
- Install git locally. ::
|
||||
#. Install git locally. For Debian/Ubuntu, execute::
|
||||
|
||||
sudo apt-get install git
|
||||
|
||||
- Ensure your ``.gitconfig`` file has your name and email address. ::
|
||||
For Fedora, execute::
|
||||
|
||||
sudo yum install git
|
||||
|
||||
For CentOS/RHEL, execute::
|
||||
|
||||
sudo yum 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).
|
||||
For example::
|
||||
|
||||
- Fork the Ceph project.
|
||||
git config --global user.name "John Doe"
|
||||
git config --global user.email johndoe@example.com
|
||||
|
||||
- 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.
|
||||
#. 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.
|
||||
|
||||
|
||||
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.
|
||||
@ -117,7 +131,7 @@ 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
|
||||
.. note:: Please do not mingle 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
|
||||
@ -136,7 +150,7 @@ If it doesn't exist, create your branch::
|
||||
Make a Change
|
||||
-------------
|
||||
|
||||
Modifying a document simply involves opening a restructuredText file, changing
|
||||
Modifying a document involves opening a restructuredText file, changing
|
||||
its contents, and saving the changes. See `Documentation Style Guide`_ for
|
||||
details on syntax requirements.
|
||||
|
||||
@ -160,47 +174,41 @@ Deleting a document involves removing it from the repository with ``git rm
|
||||
|
||||
git rm doc/rados/example.rst
|
||||
|
||||
You must also remove any reference to the document from other documents.
|
||||
You must also remove any reference to a deleted document from other documents.
|
||||
|
||||
|
||||
Build the Source
|
||||
----------------
|
||||
|
||||
To build the documentation, navigate to the ``ceph`` repository directory;
|
||||
then execute the build script::
|
||||
To build the documentation, navigate to the ``ceph`` repository directory::
|
||||
|
||||
cd ceph
|
||||
|
||||
To build the documentation on Debian/Ubuntu, execute::
|
||||
|
||||
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.
|
||||
To build the documentation on Fedora, execute::
|
||||
|
||||
admin/build-doc
|
||||
|
||||
To build the documentation on CentOS/RHEL, execute::
|
||||
|
||||
admin/build-doc
|
||||
|
||||
Executing ``admin/build-doc`` will create a ``build-doc`` directory under ``ceph``.
|
||||
You may need to create a directory under ``ceph/build-doc`` for output of Javadoc
|
||||
files. ::
|
||||
|
||||
mkdir -p output/html/api/libcephfs-java/javadoc
|
||||
|
||||
The build script ``build-doc`` will produce an output 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!
|
||||
|
||||
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::
|
||||
|
||||
@ -209,16 +217,149 @@ to view it::
|
||||
There should be 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 generally distribution agnostic. The first
|
||||
time you build Ceph documentation, it will generate a doxygen XML tree, which
|
||||
is a bit time consuming.
|
||||
|
||||
Python Sphinx does have some dependencies that vary across distributions. The
|
||||
first time you build the documentation, the script will notify you if you do not
|
||||
have the dependencies installed. To run Sphinx and build documentation successfully,
|
||||
the following packages are required:
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style>
|
||||
<table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3>
|
||||
|
||||
- gcc
|
||||
- python-dev
|
||||
- python-pip
|
||||
- python-virtualenv
|
||||
- python-sphinx
|
||||
- libxml2-dev
|
||||
- libxslt1-dev
|
||||
- doxygen
|
||||
- graphviz
|
||||
- ant
|
||||
- ditaa
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</td><td><h3>Fedora</h3>
|
||||
|
||||
- gcc
|
||||
- python-devel
|
||||
- python-pip
|
||||
- python-virtualenv
|
||||
- python-docutils
|
||||
- python-jinja2
|
||||
- python-pygments
|
||||
- python-sphinx
|
||||
- libxml2-devel
|
||||
- libxslt1-devel
|
||||
- doxygen
|
||||
- graphviz
|
||||
- ant
|
||||
- ditaa
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</td><td><h3>CentOS/RHEL</h3>
|
||||
|
||||
- gcc
|
||||
- python-devel
|
||||
- python-pip
|
||||
- python-virtualenv
|
||||
- python-docutils
|
||||
- python-jinja2
|
||||
- python-pygments
|
||||
- python-sphinx
|
||||
- libxml2-dev
|
||||
- libxslt1-dev
|
||||
- doxygen
|
||||
- graphviz
|
||||
- ant
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</td></tr></tbody></table>
|
||||
|
||||
|
||||
Install each dependency that isn't installed on your host. For Debian/Ubuntu
|
||||
distributions, execute the following::
|
||||
|
||||
sudo apt-get install gcc python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen graphviz ant ditaa
|
||||
sudo apt-get install python-sphinx
|
||||
|
||||
For Fedora distributions, execute the following::
|
||||
|
||||
sudo yum install gcc python-devel python-pip python-virtualenv 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 have ``epel`` (Extra
|
||||
Packages for Enterprise Linux) repository as it provides some extra packages
|
||||
which are not available in the default repository. To install ``epel``, execute
|
||||
the following::
|
||||
|
||||
wget http://ftp.riken.jp/Linux/fedora/epel/7/x86_64/e/epel-release-7-2.noarch.rpm
|
||||
sudo yum install epel-release-7-2.noarch.rpm
|
||||
|
||||
For CentOS/RHEL distributions, execute the following::
|
||||
|
||||
sudo yum install gcc python-devel python-pip python-virtualenv 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 and ``epel`` repositories. So, use http://rpmfind.net/ to find the
|
||||
packages. Then, download them from a mirror and install them. For example::
|
||||
|
||||
wget ftp://rpmfind.net/linux/centos/7.0.1406/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 ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm
|
||||
sudo yum install python-pygments-1.4-9.el7.noarch.rpm
|
||||
wget ftp://rpmfind.net/linux/centos/7.0.1406/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 ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/python-sphinx-1.1.3-8.el7.noarch.rpm
|
||||
sudo yum install python-sphinx-1.1.3-8.el7.noarch.rpm
|
||||
|
||||
Ceph documentation makes extensive use of `ditaa`_, which isn't presently built
|
||||
for CentOS/RHEL7. You must install ``ditaa`` if you are making changes to
|
||||
``ditaa`` diagrams so that you can verify that they render properly before you
|
||||
commit new or modified ``ditaa`` diagrams. You may retrieve compatible required
|
||||
packages for CentOS/RHEL distributions and install them manually. To run ``ditaa``
|
||||
on CentOS/RHEL7, following dependencies are required:
|
||||
|
||||
- jericho-html
|
||||
- jai-imageio-core
|
||||
- batik
|
||||
|
||||
Use http://rpmfind.net/ to find compatible ``ditaa`` and the dependencies.
|
||||
Then, download them from a mirror and install them. For example::
|
||||
|
||||
wget ftp://rpmfind.net/linux/fedora/linux/releases/20/Everything/x86_64/os/Packages/j/jericho-html-3.2-6.fc20.noarch.rpm
|
||||
sudo yum install jericho-html-3.2-6.fc20.noarch.rpm
|
||||
wget ftp://rpmfind.net/linux/centos/7.0.1406/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 ftp://rpmfind.net/linux/centos/7.0.1406/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 ftp://rpmfind.net/linux/fedora/linux/releases/20/Everything/x86_64/os/Packages/d/ditaa-0.9-10.r74.fc20.noarch.rpm
|
||||
sudo yum install ditaa-0.9-10.r74.fc20.noarch.rpm
|
||||
|
||||
.. important:: Do not install the ``fc21`` rpm for ``ditaa`` as it uses a ``JRE``
|
||||
newer than the default installed in CentOS/RHEL7 which causes a conflict, throws
|
||||
an ``Exception`` and doesn't allow the application to run.
|
||||
|
||||
Once you have installed all these packages, build the documentation by following
|
||||
the steps given in ``Build the Source``.
|
||||
|
||||
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
|
||||
@ -267,13 +408,37 @@ To commit changes, execute the following::
|
||||
|
||||
git commit -a
|
||||
|
||||
You can also a graphical editor like ``gitk`` and ``git-gui``. ::
|
||||
|
||||
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.
|
||||
|
||||
|
||||
For Debian/Ubuntu, execute::
|
||||
|
||||
sudo apt-get install gitk git-gui
|
||||
|
||||
For Fedora, execute::
|
||||
|
||||
sudo yum install gitk git-gui
|
||||
|
||||
In CentOS/RHEL7, ``gitk`` and ``git-gui`` are not available in default or
|
||||
``epel`` repository. So, use http://rpmfind.net/ to find them. Then, download
|
||||
them from a mirror and install them. For example::
|
||||
|
||||
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/gitk-1.8.3.1-4.el7.noarch.rpm
|
||||
sudo yum install gitk-1.8.3.1-4.el7.noarch.rpm
|
||||
wget ftp://rpmfind.net/linux/centos/7.0.1406/os/x86_64/Packages/git-gui-1.8.3.1-4.el7.noarch.rpm
|
||||
sudo yum install git-gui-1.8.3.1-4.el7.noarch.rpm
|
||||
|
||||
Then, execute::
|
||||
|
||||
cd {git-ceph-repo-path}
|
||||
gitk
|
||||
|
||||
Then select **File->Start git gui** to activate the graphical user interface.
|
||||
Finally, select **File->Start git gui** to activate the graphical user interface.
|
||||
|
||||
|
||||
Push the Change
|
||||
@ -431,14 +596,11 @@ incorporate the link destination inline; however, we prefer to use the use the
|
||||
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
|
||||
.. _ditaa: http://ditaa.sourceforge.net/
|
||||
.. _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
|
||||
@ -446,4 +608,4 @@ improves the readability of the document in a command line interface.
|
||||
.. _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
|
||||
.. _John Wilkins: mailto:jowilkin@redhat.com
|
||||
Loading…
Reference in New Issue
Block a user