aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorjdenisco <jdenisco@cisco.com>2018-09-24 14:59:33 -0400
committerDamjan Marion <dmarion@me.com>2018-09-24 21:37:00 +0000
commit3138d723091234a3534baa8b1bbaad31df6fb8d6 (patch)
tree6d739fda1349dd98cdb6d0ef54743015b97c3fd0
parentedb3a9bca826ddaaf5f3c7ee83f9e474bd2a2e11 (diff)
Add the sphinx docs build options
Change-Id: If7ac5b41ca4ac602a100b616b37d07f658fd6a90 Signed-off-by: jdenisco <jdenisco@cisco.com>
-rw-r--r--.gitignore2
-rw-r--r--Makefile19
-rw-r--r--docs/gettingstarted/writingdocs/buildingrst.rst20
-rwxr-xr-xdocs/scripts/sphinx-make.sh14
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
diff --git a/Makefile b/Makefile
index a9bea9d254c..36c7a5a741d 100644
--- a/Makefile
+++ b/Makefile
@@ -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