Update Sphinx version and versioning process
- Updated to newer Sphinx version
- Changed to use doc8 to check .rst files
- Added a dictionary (dict.txt) and spellchecking
- Reformatted and fixed issues that were found in the content
Change-Id: If7b35e01ee8be25dbbd1ecd0e67b264aa6cc2a94
diff --git a/Makefile b/Makefile
index 724d01c..d1160da 100644
--- a/Makefile
+++ b/Makefile
@@ -10,46 +10,51 @@
SOURCEDIR ?= .
BUILDDIR ?= _build
+VENV_NAME := doc_venv
+
# Put it first so that "make" without argument is like "make help".
-help: doc_venv
- source ./doc_venv/bin/activate ;\
+help: $(VENV_NAME)
+ source ./$(VENV_NAME)/bin/activate ;\
$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help lint reload Makefile test
# Create the virtualenv with all the tools installed
-doc_venv:
- virtualenv -p python3 doc_venv ;\
- source ./doc_venv/bin/activate ;\
- pip install livereload ;\
+$(VENV_NAME):
+ virtualenv -p python3 $(VENV_NAME) ;\
+ source ./$(VENV_NAME)/bin/activate ;\
pip install -r requirements.txt
# automatically reload changes in browser as they're made
-reload: doc_venv
- source ./doc_venv/bin/activate ;\
- set -u ;\
+reload: $(VENV_NAME)
+ source $</bin/activate ; set -u ;\
sphinx-reload $(SOURCEDIR)
+# build multiple versions
+multiversion: $(VENV_NAME) Makefile
+ source $</bin/activate ; set -u ;\
+ sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
+ cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
+
# lint and link verification. linkcheck is built into sphinx
-test: lint linkcheck
+test: lint spelling linkcheck
-lint: rst-lint
+lint: doc8
-rst-lint: doc_venv
- source ./doc_venv/bin/activate ;\
- set -u ;\
- rstcheck -r $$(find . -name \*.rst ! -path "*doc_venv*")
+doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS)
+ source $</bin/activate ; set -u ;\
+ doc8 --max-line-length 119 \
+ $$(find . -name \*.rst ! -path "*venv*" ! -path "*vendor*" ! -path "*repos*" )
# clean up
clean:
rm -rf $(BUILDDIR)
clean-all: clean
- rm -rf doc_venv
+ rm -rf $(VENV_NAME)
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile doc_venv | $(OTHER_REPO_DOCS)
- source ./doc_venv/bin/activate ;\
- set -u ;\
+%: $(VENV_NAME) | $(OTHER_REPO_DOCS)
+ source $</bin/activate ; set -u ;\
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)