diff options
Diffstat (limited to 'doc/dev/generatedocs.rst')
| -rw-r--r-- | doc/dev/generatedocs.rst | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/doc/dev/generatedocs.rst b/doc/dev/generatedocs.rst new file mode 100644 index 000000000..8632eb176 --- /dev/null +++ b/doc/dev/generatedocs.rst @@ -0,0 +1,83 @@ +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. |