1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
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.
|
