From: Kefu Chai <kchai@redhat.com>
Date: Fri, 11 Dec 2020 13:33:41 +0000 (+0800)
Subject: admin/build-doc: add livehtml target
X-Git-Tag: v16.1.0~289^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=34f74e8a376a528efff5e0a1c530834c2ba02e92;p=ceph.git

admin/build-doc: add livehtml target

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>
---

diff --git a/admin/build-doc b/admin/build-doc
index 98614b7db4e1..a5c4d41514da 100755
--- a/admin/build-doc
+++ b/admin/build-doc
@@ -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
 
 #
diff --git a/doc/dev/generatedocs.rst b/doc/dev/generatedocs.rst
index d9d0c0730fca..7999de2e57fc 100644
--- a/doc/dev/generatedocs.rst
+++ b/doc/dev/generatedocs.rst
@@ -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
 -------------------