blob: a5219841fd5d4e0205d4990113ea5f843b931d10 [file] [log] [blame]
Zack Williams071eda22019-05-15 18:19:51 -07001# Makefile for Sphinx documentation
2
3# use bash for pushd/popd, and to fail quickly
4SHELL = bash -e -o pipefail
5
6# You can set these variables from the command line.
7SPHINXOPTS ?=
8SPHINXBUILD ?= sphinx-build
9SOURCEDIR ?= .
10BUILDDIR ?= _build
11
Zack Williams88df4742019-12-20 08:24:47 -070012# Other repos with documentation to include.
13# edit the `git_refs` file with the commit/tag/branch that you want to use
Andrea Campanella13f26f52021-01-28 13:47:40 +010014OTHER_REPO_DOCS ?= bbsim cord-tester ofagent-go openolt voltctl voltha-openolt-adapter voltha-openonu-adapter voltha-openonu-adapter-go voltha-protos voltha-system-tests kind-voltha device-management-interface
Zack Williams88df4742019-12-20 08:24:47 -070015
Zack Williams16042b62020-03-29 22:03:16 -070016# Static docs, built by other means (usually robot framework)
17STATIC_DOCS := _static/voltha-system-tests _static/cord-tester
18
19# name of python virtualenv that is used to run commands
20VENV_NAME := venv_docs
Zack Williams071eda22019-05-15 18:19:51 -070021
Zack Williams88df4742019-12-20 08:24:47 -070022.PHONY: help test lint reload Makefile prep
Zack Williams071eda22019-05-15 18:19:51 -070023
Zack Williams16042b62020-03-29 22:03:16 -070024# Put it first so that "make" without argument is like "make help".
25help: $(VENV_NAME)
26 source $</bin/activate ; set -u ;\
27 $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
28
Zack Williams071eda22019-05-15 18:19:51 -070029# Create the virtualenv with all the tools installed
Zack Williams16042b62020-03-29 22:03:16 -070030$(VENV_NAME):
31 virtualenv -p python3 $(VENV_NAME) ;\
Zack Williamsc6460c22019-12-18 14:54:43 -070032 source $@/bin/activate ;\
Zack Williams071eda22019-05-15 18:19:51 -070033 pip install -r requirements.txt
34
35# automatically reload changes in browser as they're made
Zack Williams16042b62020-03-29 22:03:16 -070036reload: $(VENV_NAME)
Zack Williamsc6460c22019-12-18 14:54:43 -070037 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -070038 sphinx-reload $(SOURCEDIR)
39
40# lint and link verification. linkcheck is part of sphinx
41test: lint linkcheck
42
Zack Williamsc6460c22019-12-18 14:54:43 -070043lint: doc8
Zack Williams071eda22019-05-15 18:19:51 -070044
Zack Williams16042b62020-03-29 22:03:16 -070045doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS)
Zack Williamsc6460c22019-12-18 14:54:43 -070046 source $</bin/activate ; set -u ;\
47 doc8 --max-line-length 119 \
Zack Williams16042b62020-03-29 22:03:16 -070048 $$(find . -name \*.rst ! -path "*venv*" ! -path "*vendor*" ! -path "*repos*" )
Zack Williams071eda22019-05-15 18:19:51 -070049
50# markdown linting
51# currently not enabled, should be added to lint target
52LINT_STYLE ?= mdl_strict.rb
53md-lint: | $(OTHER_REPO_DOCS)
54 @echo "markdownlint(mdl) version: `mdl --version`"
55 @echo "style config:"
56 @echo "---"
57 @cat $(LINT_STYLE)
58 @echo "---"
Zack Williams16042b62020-03-29 22:03:16 -070059 mdl -s $(LINT_STYLE) `find -L $(SOURCEDIR) ! -path "./_$(VENV_NAME)/*" ! -path "./_build/*" ! -path "./repos/*" ! -path "*vendor*" -name "*.md"`
Zack Williams071eda22019-05-15 18:19:51 -070060
61# clean up
62clean:
Zack Williams16042b62020-03-29 22:03:16 -070063 rm -rf $(BUILDDIR) $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williams071eda22019-05-15 18:19:51 -070064
65clean-all: clean
Zack Williams16042b62020-03-29 22:03:16 -070066 rm -rf $(VENV_NAME) repos
Zack Williams071eda22019-05-15 18:19:51 -070067
Zack Williams071eda22019-05-15 18:19:51 -070068# checkout the repos inside repos/ dir
69repos:
70 mkdir repos
71
72# build directory paths in repos/* to perform 'git clone <repo>' into
73CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
74
75# Host holding the git server
76REPO_HOST ?= https://gerrit.opencord.org
77
78# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
79# pre-populate it under repos/ with the specific commit to being validated
80SKIP_CHECKOUT ?=
81
Zack Williams88df4742019-12-20 08:24:47 -070082# clone (only if doesn't exist)
Zack Williams071eda22019-05-15 18:19:51 -070083$(CHECKOUT_REPOS): | repos
Zack Williams071eda22019-05-15 18:19:51 -070084 if [ ! -d '$@' ] ;\
85 then git clone $(REPO_HOST)/$(@F) $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -070086 fi
87
Zack Williams33085522020-02-28 11:41:01 -070088# checkout correct ref if not under test, then copy subdirectories into main
Zack Williams17e34022019-12-20 13:51:54 -070089# docs dir
Zack Williams071eda22019-05-15 18:19:51 -070090$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
Zack Williams88df4742019-12-20 08:24:47 -070091 if [ "$(SKIP_CHECKOUT)" != "$@" ] ;\
92 then GIT_REF=`grep '^$@ ' git_refs | awk '{print $$3}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -070093 cd "repos/$@" && git checkout $$GIT_REF ;\
Zack Williams88df4742019-12-20 08:24:47 -070094 fi
Zack Williams17e34022019-12-20 13:51:54 -070095 GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
Zack Williams33085522020-02-28 11:41:01 -070096 cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
Zack Williams071eda22019-05-15 18:19:51 -070097
Andrea Campanella92bd59b2020-01-30 17:26:32 +010098# Build Robot documentation in voltha-system-tests and copy it into _static.
99_static/voltha-system-tests: | $(OTHER_REPO_DOCS)
100 make -C voltha-system-tests gendocs
101 mkdir -p $@
102 cp -r voltha-system-tests/gendocs/* $@
103
Andy Bavier39d67b12020-02-27 16:08:52 -0700104# Build Robot documentation in cord-tester and copy it into _static.
105_static/cord-tester: | $(OTHER_REPO_DOCS)
106 make -C cord-tester gendocs
107 mkdir -p $@
108 cp -r cord-tester/gendocs/* $@
109
Zack Williams071eda22019-05-15 18:19:51 -0700110# generate a list of git checksums suitable for updating git_refs
111freeze: repos
112 @for repo in $(OTHER_REPO_DOCS) ; do \
113 GIT_SUBDIR=`grep "^$$repo " git_refs | awk '{print $$2}'` ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700114 cd "repos/$$repo" > /dev/null ;\
Zack Williams071eda22019-05-15 18:19:51 -0700115 HEAD_SHA=`git rev-parse HEAD` ;\
116 printf "%-24s %-8s %-40s\n" $$repo $$GIT_SUBDIR $$HEAD_SHA ;\
Zack Williams6c1703f2019-12-20 15:31:58 -0700117 cd ../.. ;\
Zack Williams071eda22019-05-15 18:19:51 -0700118 done
119
Zack Williams16042b62020-03-29 22:03:16 -0700120# build multiple versions
121multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
Zack Williams88df4742019-12-20 08:24:47 -0700122 source $</bin/activate ; set -u ;\
Zack Williams16042b62020-03-29 22:03:16 -0700123 sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
124 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
Zack Williams88df4742019-12-20 08:24:47 -0700125
Zack Williams16042b62020-03-29 22:03:16 -0700126# prep target - used in sphinx-multiversion to properly link
127prep: | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Andy Bavier5dee6ae2020-01-29 16:03:40 -0700128
Zack Williams071eda22019-05-15 18:19:51 -0700129# Catch-all target: route all unknown targets to Sphinx using the new
130# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
Zack Williams16042b62020-03-29 22:03:16 -0700131%: $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
Zack Williamsc6460c22019-12-18 14:54:43 -0700132 source $</bin/activate ; set -u ;\
Zack Williams071eda22019-05-15 18:19:51 -0700133 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)