mirror of
https://github.com/ceph/ceph
synced 2024-12-25 21:03:31 +00:00
84 lines
2.2 KiB
ReStructuredText
84 lines
2.2 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 <https://www.sphinx-doc.org/en/master/>`_.
|
|
|
|
To build the Ceph documentation set, you must:
|
|
|
|
1. Clone the Ceph repository
|
|
2. Install the required tools
|
|
3. Build the documents
|
|
4. Demo the documents (Optional)
|
|
|
|
.. highlight:: bash
|
|
|
|
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
|
|
|
|
To clone the Ceph repository, execute::
|
|
|
|
git clone git://github.com/ceph/ceph
|
|
|
|
You should have a full copy of the Ceph repository.
|
|
|
|
|
|
Install the Required Tools
|
|
--------------------------
|
|
|
|
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.
|
|
|
|
|
|
Build the Documents
|
|
-------------------
|
|
|
|
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.
|
|
|
|
Demo the Documents
|
|
-------------------
|
|
|
|
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.
|