BUILDING CEPH DOCUMENTATION
===========================

Ceph utilizes Python's "Sphinx" documentation tool. For details on
the Sphinx documentation tool, refer to: http://sphinx.pocoo.org/

To build the Ceph documentation set, you must:

1. Clone the Ceph repository
2. Install the required tools
3. Execute admin/build-doc from the ceph directory.

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 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 think you have the required tools to run Sphinx, 
navigate to the Ceph repository and execute the build:

	$ cd ceph
	$ admin/build-doc
	
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
	
Once you have installed all the dependencies, execute the build again:

	$ 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.