mirror of
https://github.com/ceph/ceph
synced 2024-12-28 14:34:13 +00:00
b8317f5e1e
Added a brief section about how to demo Ceph documentation changes. Signed-off-by: James McClune <jmcclune@mcclunetechnologies.net>
71 lines
1.8 KiB
ReStructuredText
71 lines
1.8 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)
|
|
|
|
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.
|
|
|
|
|
|
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.
|