From 34f74e8a376a528efff5e0a1c530834c2ba02e92 Mon Sep 17 00:00:00 2001
From: Kefu Chai <kchai@redhat.com>
Date: Fri, 11 Dec 2020 21:33:41 +0800
Subject: [PATCH] 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>
---
 admin/build-doc          | 35 ++++++++++++++++++++++++-----------
 doc/dev/generatedocs.rst | 11 +++++++++++
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/admin/build-doc b/admin/build-doc
index 98614b7db4e..a5c4d41514d 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 d9d0c0730fc..7999de2e57f 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
 -------------------
-- 
2.39.5