diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile | 19 | ||||
| -rw-r--r-- | docs/gettingstarted/writingdocs/buildingrst.rst | 20 | ||||
| -rwxr-xr-x | docs/scripts/sphinx-make.sh | 14 |
4 files changed, 46 insertions, 9 deletions
diff --git a/.gitignore b/.gitignore index 1885a85745e..b11564e5e4d 100644 --- a/.gitignore +++ b/.gitignore @@ -82,7 +82,7 @@ GTAGS /build-root/.doxygen-bootstrap.ok /build-root/.doxygen-siphon.dep /docs/_build -/env +/sphinx_venv !/docs/Makefile # indent backup files @@ -217,6 +217,9 @@ help: @echo " doxygen - (re)generate documentation" @echo " bootstrap-doxygen - setup Doxygen dependencies" @echo " wipe-doxygen - wipe all generated documentation" + @echo " docs - Build the Sphinx documentation" + @echo " docs-venv - Build the virtual environment for the Sphinx docs" + @echo " docs-clean - Remove the generated files from the Sphinx docs" @echo " test-doc - generate documentation for test framework" @echo " test-wipe-doc - wipe documentation for test framework" @echo " test-cov - generate code coverage report for test framework" @@ -537,6 +540,22 @@ doxygen: wipe-doxygen: $(call make-doxy) +# Sphinx Documents +export DOCS_DIR = $(WS_ROOT)/docs +export VENV_DIR = $(WS_ROOT)/sphinx_venv +export SPHINX_SCRIPTS_DIR = $(WS_ROOT)/docs/scripts + +.PHONY: docs-venv docs docs-clean + +docs-venv: + @($(SPHINX_SCRIPTS_DIR)/sphinx-make.sh venv) + +docs: $(DOCS_DIR) + @($(SPHINX_SCRIPTS_DIR)/sphinx-make.sh html) + +docs-clean: + @($(SPHINX_SCRIPTS_DIR)/sphinx-make.sh clean) + verify: install-dep $(BR)/.deps.ok install-ext-deps $(call banner,"Building for PLATFORM=vpp using gcc") @make -C build-root PLATFORM=vpp TAG=vpp wipe-all install-packages diff --git a/docs/gettingstarted/writingdocs/buildingrst.rst b/docs/gettingstarted/writingdocs/buildingrst.rst index 5134bb395ee..46830ca2580 100644 --- a/docs/gettingstarted/writingdocs/buildingrst.rst +++ b/docs/gettingstarted/writingdocs/buildingrst.rst @@ -32,11 +32,7 @@ In the vpp root directory on your system, run: .. code-block:: console - $ python -m pip install --user virtualenv - $ python -m virtualenv env - $ source env/bin/activate - $ pip install -r docs/etc/requirements.txt - $ cd docs + $ make docs-venv Which installs all the required applications into it's own, isolated, virtual environment, so as to not interfere with other builds that may use different versions of software. @@ -44,12 +40,20 @@ interfere with other builds that may use different versions of software. Build the html files ====================== -Be sure you are in your vpp-docs/docs directory, since that is where Sphinx will look for your **conf.py** -file, and build the **.rst** files into an **index.html** file: +Build the html **index.html** file: .. code-block:: console - $ make html + $ make docs + +Clean the environment +====================== + +Delete all the generated files with the following: + +.. code-block:: console + + $ make docs-clean View the results ================= diff --git a/docs/scripts/sphinx-make.sh b/docs/scripts/sphinx-make.sh new file mode 100755 index 00000000000..e95b3eba066 --- /dev/null +++ b/docs/scripts/sphinx-make.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +if [ "$1" == "venv" ] +then + python -m pip install --user virtualenv + python -m virtualenv $VENV_DIR + source $VENV_DIR/bin/activate; + pip install -r $DOCS_DIR/etc/requirements.txt +else + source $VENV_DIR/bin/activate; + make -C $DOCS_DIR $1 +fi + +deactivate |