mirror of
https://github.com/ceph/ceph
synced 2025-01-08 04:01:48 +00:00
34f74e8a37
it is time-consuming to rebuild the python bindings every time we rebuild the document, it'd be ideal if we could just build document. in this change, in addition to "html" and "doc", "livehtml" argument is now supported by build-doc script, so one can just use ./build-doc livehtml to build and start a web server. whenever a change in doc/ is detected, the document is rebuilt. for more details, see https://pypi.org/project/sphinx-autobuild/ Signed-off-by: Kefu Chai <kchai@redhat.com>
82 lines
2.2 KiB
ReStructuredText
82 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)
|
|
|
|
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.
|