Update Sphinx
Fix font licensing
Add spelling dict tests
Remove sphinx docs which were duplicated everywhere, refer to ONF main
docs site which is more complete
Add code of conduct and link
Change-Id: I35764345f09a4dcb082a73d4a1c0c04ce889c4a3
diff --git a/Makefile b/Makefile
index 2b41867..d94af44 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,8 @@
# Makefile for Sphinx documentation
+# SPDX-FileCopyrightText: © 2020 Open Networking Foundation <support@opennetworking.org>
+# SPDX-License-Identifier: Apache-2.0
+
# use bash for pushd/popd, and to fail quickly
SHELL = bash -e -o pipefail
@@ -9,57 +12,61 @@
SOURCEDIR ?= .
BUILDDIR ?= _build
-# name of python virtualenv that is used to run commands
-VENV_NAME := venv-docs
-
-.PHONY: help test lint doc8 reload Makefile prep
-
-# Put it first so that "make" without argument is like "make help".
-help: $(VENV_NAME)
- source $</bin/activate ; set -u ;\
- $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
# Create the virtualenv with all the tools installed
+VENV_NAME := venv-docs
+
+# Put it first so that "make" without argument runs "make help".
+help: $(VENV_NAME)
+ source ./$(VENV_NAME)/bin/activate ; set -u ;\
+ $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile test doc8 dict-check sort-dict license clean clean-all
+
$(VENV_NAME):
- python3 -m venv $(VENV_NAME) ;\
- source $@/bin/activate ;\
- pip install -r requirements.txt
+ python3 -m venv $@ ;\
+ source ./$@/bin/activate ;\
+ pip install -r requirements.txt
-# automatically reload changes in browser as they're made
-reload: $(VENV_NAME)
- source $</bin/activate ; set -u ;\
- sphinx-reload $(SOURCEDIR)
+# test - check that local build will lint, spelling is correct, then
+# build the html site.
+test: license doc8 dict-check spelling linkcheck
-# lint and link verification. linkcheck is part of sphinx
-test: lint spelling linkcheck
+# lint all .rst files
+doc8: $(VENV_NAME)
+ source ./$</bin/activate ; set -u;\
+ doc8 --ignore-path $< --ignore-path _build --ignore-path LICENSES --max-line-length 119
-lint: doc8
+# Words in dict.txt must be in the correct alphabetical order and must not duplicated.
+dict-check: sort-dict
+ @set -u ;\
+ git diff --exit-code dict.txt && echo "dict.txt is sorted" && exit 0 || \
+ echo "dict.txt is unsorted or needs to be added to git index" ; exit 1
-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*" )
+sort-dict:
+ @sort -u < dict.txt > dict_sorted.txt
+ @mv dict_sorted.txt dict.txt
-license: $(VENV_NAME)
- source $</bin/activate ; set -u ;\
+license: $(VENV_NAME) ## Check license with the reuse tool
+ source ./$</bin/activate ; set -u ;\
reuse --version ;\
reuse --root . lint
# clean up
clean:
- rm -rf $(BUILDDIR)
+ rm -rf "$(BUILDDIR)"
+# clean-all - delete the virtualenv too
clean-all: clean
- rm -rf $(VENV_NAME)
+ rm -rf "$(VENV_NAME)"
# build multiple versions
-multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
+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"
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
- source $</bin/activate ; set -u ;\
- $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+%: $(VENV_NAME) Makefile
+ source ./$</bin/activate ; set -u;\
+ $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)