Add sphinxcontrib-versioning
- 'make versioned' target to build w/versions, and supporting 'make
prep' target.
- Rework how checking out refs in repos are done in the makefile
- Change versioning method from VERSION file to conf.py
- use fork of sphinxconfig-versioning to deal with repos/ structure
- move OTHER_REPO_DOCS in Makefile so doc8 target requires that docs are
checked out in repos/ .
Change-Id: I6f5d6eee324bbbe31b71e1af596f0d8feb8f8785
diff --git a/Makefile b/Makefile
index 349938d..027660a 100644
--- a/Makefile
+++ b/Makefile
@@ -9,12 +9,16 @@
SOURCEDIR ?= .
BUILDDIR ?= _build
+# Other repos with documentation to include.
+# edit the `git_refs` file with the commit/tag/branch that you want to use
+OTHER_REPO_DOCS ?= bbsim voltha-go voltha-openolt-adapter voltha-openonu-adapter voltha-protos
+
# Put it first so that "make" without argument is like "make help".
help: doc_venv
source $</bin/activate ; set -u ;\
$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-.PHONY: help test lint reload Makefile
+.PHONY: help test lint reload Makefile prep
# Create the virtualenv with all the tools installed
doc_venv:
@@ -56,10 +60,6 @@
clean-all: clean
rm -rf doc_venv repos
-# Other repos with documentation to include.
-# edit the `git_refs` file with the commit/tag/branch that you want to use
-OTHER_REPO_DOCS ?= bbsim voltha-go voltha-openolt-adapter voltha-openonu-adapter voltha-protos
-
# checkout the repos inside repos/ dir
repos:
mkdir repos
@@ -74,34 +74,44 @@
# pre-populate it under repos/ with the specific commit to being validated
SKIP_CHECKOUT ?=
-# clone (only if doesn't exist), then checkout ref in repos/*
+# clone (only if doesn't exist)
$(CHECKOUT_REPOS): | repos
- GIT_REF=`grep '^$(@F) ' git_refs | awk '{print $$3}'` ;\
if [ ! -d '$@' ] ;\
then git clone $(REPO_HOST)/$(@F) $@ ;\
- fi ;\
- if [ "$(SKIP_CHECKOUT)" = "$(@F)" ] ;\
- then echo "Skipping checkout of repo $(SKIP_CHECKOUT) as it's being tested" ;\
- else pushd $@ ;\
- git checkout $$GIT_REF ;\
- popd ;\
fi
-# link subdirectories (if applicable) into main docs dir
+# link subdirectories (if applicable) into main docs dir, then checkout ref if
+# not under test
$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
- ln -s repos/$(@)$$GIT_SUBDIR $@
+ ln -s repos/$(@)$$GIT_SUBDIR $@ ;\
+ if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
+ then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
+ pushd $@ ;\
+ git checkout $$GIT_REF ;\
+ popd ;\
+ fi
# generate a list of git checksums suitable for updating git_refs
freeze: repos
@for repo in $(OTHER_REPO_DOCS) ; do \
GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
- cd "repos/$$repo" > /dev/null ;\
+ pushd "repos/$$repo" > /dev/null ;\
HEAD_SHA=`git rev-parse HEAD` ;\
printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
- cd ../.. ;\
+ popd ;\
done
+# use sphinxcontrib-versioning to make a versioned copy of the
+# NOTE: document root is now in _build, not _build/html
+versioned: doc_venv Makefile | $(OTHER_REPO_DOCS)
+ source $</bin/activate ; set -u ;\
+ sphinx-versioning build -r master "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# prep target - used in sphinxcontrib-versioning to create versioned repos when
+# building multiple versions
+prep: | $(OTHER_REPO_DOCS)
+
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: doc_venv Makefile | $(OTHER_REPO_DOCS)