doc: Add make render-docs-live-preview target

- Install dependencies inside a virtualenv using pipenv and run sphinx-autobuild for real-time preview. - Update PyYAML dependency to 5.3.1. Pipenv complains about beta version dependencies by default. - Update the Documentation page. Signed-off-by: Michi Mutsuzaki <michi@isovalent.com>
cilium · May 19, 2020 · 38abe89 · 38abe89
1 parent cc52749
commit 38abe89
Show file tree

Hide file tree

Showing 5 changed files with 30 additions and 7 deletions.
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
@@ -1,2 +1,5 @@
 _build
 _api
+_preview
+Pipfile
+Pipfile.lock
diff --git a/Documentation/Makefile b/Documentation/Makefile
@@ -9,7 +9,7 @@ include ../Makefile.quiet
 default: html
 
 clean:
-	-$(QUIET)rm -rf _build
+	-$(QUIET)rm -rf _build _preview Pipfile Pipfile.lock
 
 builder-image: Dockerfile requirements.txt
 	$(QUIET)tar c requirements.txt Dockerfile \
@@ -61,3 +61,13 @@ run-server: stop-server
 
 stop-server:
 	-$(QUIET)$(CONTAINER_ENGINE) container rm --force --volumes docs-cilium
+
+pipenv:
+	@which pipenv > /dev/null || (echo "Please install pipenv: https://pipenv.pypa.io/en/latest/#install-pipenv-today"; exit 1)
+
+pipenv-install: pipenv
+	pipenv --rm || true
+	pipenv install --three -r requirements.txt
+
+live-preview: pipenv
+	pipenv run sphinx-autobuild -B $(SPHINX_OPTS) -i *.swp -Q . _preview
diff --git a/Documentation/contributing/testing/documentation.rst b/Documentation/contributing/testing/documentation.rst
@@ -7,7 +7,18 @@
 Documentation
 =============
 
-Whenever making changes to Cilium documentation you should check that you did not introduce any new warnings or errors, and also check that your changes look as you intended.  To do this you can build the docs:
+First, start a local document server that automatically refreshes when you save files for
+real-time preview. After installing `pipenv <https://pipenv.pypa.io/en/latest/#install-pipenv-today>`_,
+run:
+
+::
+
+    $ make render-docs-live-preview
+
+and preview the documentation at http://localhost:8000/ as you make changes. After making changes to
+Cilium documentation you should check that you did not introduce any new warnings or errors, and also
+check that your changes look as you intended one last time before opening a pull request. To do this
+you can build the docs:
 
 ::
 
@@ -16,7 +27,3 @@ Whenever making changes to Cilium documentation you should check that you did no
 This generates documentation files and starts a web server using a Docker container. You can
 view the updated documentation by opening either ``Documentation/_build/html/index.html`` or
 http://localhost:9081 in a browser.
-
-.. note:: ``make render-docs`` is relatively slow since it performs syntax and spelling checks.
-          You can run ``make render-docs SKIP_LINT=1`` to render the documentation without performing
-          these checks while you iterate on updating the documentation.
diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt
@@ -11,7 +11,7 @@ MarkupSafe==1.1.1
 pyenchant==2.0.0
 Pygments==2.4.2
 pytz==2018.7
-PyYAML==4.2b1
+PyYAML==5.3.1
 requests==2.20.0
 six==1.11.0
 snowballstemmer==1.2.1

diff --git a/Makefile b/Makefile
@@ -596,6 +596,9 @@ update-authors:
 render-docs:
 	$(MAKE) -C Documentation html run-server
 
+render-docs-live-preview:
+	$(MAKE) -C Documentation pipenv-install live-preview
+
 manpages:
 	-rm -r man
 	mkdir -p man