RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2025-04-01 23:02:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

admin/build-doc: add livehtml target

Browse Source 
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>
This commit is contained in:
Kefu Chai 2020-12-11 21:33:41 +08:00
parent 4d6d1465ea
commit 34f74e8a37
2 changed files with 35 additions and 11 deletions

35
admin/build-doc
View File

@ -87,26 +87,39 @@ for bind in rados rbd cephfs rgw; do
BUILD_DOC=1 $vdir/bin/pip install --upgrade $TOPDIR/src/pybind/${bind}
done
if [ -z "$@" ]; then
for opt in "$@"; do
case $opt in
html|man|livehtml)
sphinx_targets="$sphinx_targets $opt"
shift
;;
--)
shift
break
esac
done
if [ -z "$sphinx_targets" ]; then
sphinx_targets="html man"
else
sphinx_targets=$@
fi
for target in $sphinx_targets; do
builder=$target
# Build with -W so that warnings are treated as errors and this fails
case $target in
html)
builder=dirhtml
$vdir/bin/sphinx-build -W --keep-going -a -b dirhtml -d doctrees \
$TOPDIR/doc $TOPDIR/build-doc/output/$target
;;
man)
extra_opt="-t man"
$vdir/bin/sphinx-build -W --keep-going -a -b man -t man -d doctrees \
$TOPDIR/doc $TOPDIR/build-doc/output/$target
;;
livehtml)
$PIP_INSTALL --quiet sphinx-autobuild
$vdir/bin/sphinx-autobuild --re-ignore '.*\.dot' "$@" \
$TOPDIR/doc $TOPDIR/build-doc/output/html
;;
esac
# Build with -W so that warnings are treated as errors and this fails
$vdir/bin/sphinx-build -W --keep-going -a -b $builder $extra_opt -d doctrees \
$TOPDIR/doc $TOPDIR/build-doc/output/$target
done
#

11
doc/dev/generatedocs.rst
View File

@ -56,6 +56,17 @@ Once you build the documentation set, you may navigate to the source directory t
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
-------------------