mirror of https://github.com/ceph/ceph
86 lines
2.3 KiB
ReStructuredText
86 lines
2.3 KiB
ReStructuredText
Building Ceph Documentation
|
|
===========================
|
|
|
|
Ceph utilizes Python's Sphinx documentation tool. For details on
|
|
the Sphinx documentation tool, refer to `The Sphinx Documentation Tool <http://sphinx.pocoo.org/>`_.
|
|
|
|
To build the Ceph documentation set, you must:
|
|
|
|
1. Clone the Ceph repository
|
|
2. Install the required tools
|
|
3. Build the documents
|
|
|
|
Clone the Ceph Repository
|
|
-------------------------
|
|
|
|
To clone the Ceph repository, you must have ``git`` installed
|
|
on your local host. To install ``git``, execute:
|
|
|
|
``$ sudo apt-get install git``
|
|
|
|
You must also have a github account. If you do not have a
|
|
github account, go to `github <http://github.com>`_ and register.
|
|
|
|
You must set up SSH keys with github to clone the Ceph
|
|
repository. If you do not have SSH keys for github, execute:
|
|
|
|
``$ ssh-keygen -d``
|
|
|
|
Get the key to add to your github account:
|
|
|
|
``$ cat .ssh/id_dsa.pub``
|
|
|
|
Copy the public key. Then, go to your your github account,
|
|
click on **Account Settings** (*i.e.*, the tools icon); then,
|
|
click **SSH Keys** on the left side navbar.
|
|
|
|
Click **Add SSH key** in the **SSH Keys** list, enter a name for
|
|
the key, paste the key you generated, and press the **Add key**
|
|
button.
|
|
|
|
To clone the Ceph repository, execute:
|
|
|
|
``$ git clone git@github:ceph/ceph.git``
|
|
|
|
You should have a full copy of the Ceph repository.
|
|
|
|
|
|
Install the Required Tools
|
|
--------------------------
|
|
If you do not have Sphinx and its dependencies installed,
|
|
a list of dependencies will appear in the output. Install
|
|
the dependencies on your system, and then execute the build.
|
|
|
|
To run Sphinx, at least the following are required:
|
|
|
|
- ``python-dev``
|
|
- ``python-pip``
|
|
- ``python-virtualenv``
|
|
- ``libxml2-dev``
|
|
- ``libxslt-dev``
|
|
- ``doxygen``
|
|
- ``ditaa``
|
|
- ``graphviz``
|
|
|
|
Execute ``apt-get install`` for each dependency that isn't
|
|
installed on your host.
|
|
|
|
``$ apt-get install python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen ditaa graphviz``
|
|
|
|
|
|
|
|
Build the Documents
|
|
-------------------
|
|
|
|
Once you have installed all the dependencies, execute the build:
|
|
|
|
``$ cd ceph``
|
|
``$ admin/build-doc``
|
|
|
|
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.
|