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 <[email protected]>
thomasgoirand · Dec 11, 2020 · 34f74e8 · 34f74e8
1 parent 4d6d146
commit 34f74e8
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 11 deletions.
diff --git 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
@@ -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
 -------------------