diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst index 3bb4d89a0b7..3aba99c70f5 100644 --- a/doc/start/documenting-ceph.rst +++ b/doc/start/documenting-ceph.rst @@ -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 + + +

Debian/Ubuntu

+ +- gcc +- python-dev +- python-pip +- python-virtualenv +- python-sphinx +- libxml2-dev +- libxslt1-dev +- doxygen +- graphviz +- ant +- ditaa + +.. raw:: html + +

Fedora

+ +- 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 + +

CentOS/RHEL

+ +- gcc +- python-devel +- python-pip +- python-virtualenv +- python-docutils +- python-jinja2 +- python-pygments +- python-sphinx +- libxml2-dev +- libxslt1-dev +- doxygen +- graphviz +- ant + +.. raw:: html + +
+ + +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 \ No newline at end of file