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)
diff --git a/VERSION b/VERSION
deleted file mode 100644
index 97ade15..0000000
--- a/VERSION
+++ /dev/null
@@ -1 +0,0 @@
-2.2.0-dev
diff --git a/conf.py b/conf.py
index 8f6ce2d..53961f6 100644
--- a/conf.py
+++ b/conf.py
@@ -16,12 +16,6 @@
# import sys
# sys.path.insert(0, os.path.abspath('.'))
-import os
-
-def get_version():
- with open("VERSION") as f:
- return f.read().strip()
-
# -- Project information -----------------------------------------------------
project = u'VOLTHA Docs'
@@ -29,10 +23,10 @@
author = u'VOLTHA Contributors'
# The short X.Y version
-version = get_version()
+version = "2.2.0-dev"
# The full version, including alpha/beta/rc tags
-release = get_version()
+release = version
# -- General configuration ---------------------------------------------------
@@ -80,6 +74,12 @@
# Text files with lists of words that shouldn't fail the spellchecker:
spelling_word_list_filename=['dict.txt', ]
+# SCVersioning prep target commands, run in each target directory
+scv_prep_commands = [
+ 'ln -sf _root_/repos _target_/repos',
+ 'make prep',
+]
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/readme.rst b/readme.rst
index a0acf09..8486e23 100644
--- a/readme.rst
+++ b/readme.rst
@@ -32,6 +32,17 @@
reStructuredText Primer:
http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+Creating new Versions of Docs
+-----------------------------
+
+To change the version shown on the built site, change the ``versions`` variable in ``conf.py``.
+
+There is a ``make versioned`` target which will build all versions published on
+the remote to ``_build``. Note that we're using a fork of the upstream version
+of the ``sphinxcontrib-versioning`` plugin, as the original isn't actively
+maintianed, and we needed it to be able to handle the symlink checkouts of
+other repos that are incorporated.
+
Creating Diagrams
-----------------
diff --git a/requirements.txt b/requirements.txt
index 4f5937c..d523bef 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -14,5 +14,9 @@
sphinxcontrib-openapi~=0.5.0
sphinxcontrib-seqdiag~=0.8.5
sphinxcontrib-spelling~=4.2.1
+# using a fork as the main branch is broken in newer sphinx, per:
+# https://github.com/sphinx-contrib/sphinxcontrib-versioning/issues/58
+# also added functionality to support working with other repos
+git+https://github.com/zdw/sphinxcontrib-versioning@0998d870b2791eb6343c98e98d6680c1e727daee
# sphinx-autoapi~=1.2.1
# sphinxcontrib-golangdomain