doc/dev/generatedocs.rst
Ceph utilizes Python's Sphinx documentation tool. For details on
the Sphinx documentation tool, refer to The Sphinx Documentation Tool <https://www.sphinx-doc.org/en/master/>_.
To build the Ceph documentation set, you must:
.. highlight:: bash
To clone the Ceph repository, you must have git installed
on your local host. To install git, execute::
sudo apt-get install git
To clone the Ceph repository, execute::
git clone git://github.com/ceph/ceph
You should have a full copy of the Ceph repository.
To build the Ceph documentation, some dependencies are required. To know what packages are needed, you can launch this command::
cd ceph
admin/build-doc
If dependencies are missing, the command above will fail with a message that suggests you a command to install all missing dependencies.
Once you have installed all the dependencies, execute the build (the same command as above)::
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.
admin/build-doc takes a long time to prepare the environment and build the document.
But you can just rebuild the document on changes using::
admin/build-doc livehtml
This feature uses sphinx-autobuild under the hood. You can also pass options to it. For
instance, to open the browser after building the documentation::
admin/build-doc livehtml -- --open-browser
Please see sphinx-autobuild <https://pypi.org/project/sphinx-autobuild/>_ for more details.
Once you build the documentation, as described above, you can demo the rendered documents
by running serve-doc::
cd ceph
admin/serve-doc
This will serve the build-doc/output/html directory over port 8080 via
Python's SimpleHTTPServer module.