blob: 7dd066dfed06c5b0a7fa14af6a43a6e9dd7309d5 [file] [log] [blame]
Charles Chanfcfe8902022-02-02 17:06:27 -08001# SPDX-FileCopyrightText: 2021 Open Networking Foundation <info@opennetworking.org>
2# SPDX-License-Identifier: Apache-2.0
3
Zack Williams98fe2322021-09-20 15:02:11 -07004# Makefile for Sphinx documentation
5
6# use bash for pushd/popd, and to fail quickly
7SHELL = bash -e -o pipefail
8
9# You can set these variables from the command line.
10SPHINXOPTS ?= -W
11SPHINXBUILD ?= sphinx-build
12SOURCEDIR ?= .
13BUILDDIR ?= _build
14
15# name of python virtualenv that is used to run commands
Zack Williamse100ab52022-03-05 09:07:57 -070016VENV_NAME := venv-docs
Zack Williams98fe2322021-09-20 15:02:11 -070017
Zack Williamse100ab52022-03-05 09:07:57 -070018.PHONY: help Makefile test doc8 dict-check sort-dict license clean clean-all
Zack Williams98fe2322021-09-20 15:02:11 -070019
20# Put it first so that "make" without argument is like "make help".
21help: $(VENV_NAME)
22 source $</bin/activate ; set -u ;\
23 $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
24
25# Create the virtualenv with all the tools installed
26$(VENV_NAME):
Zack Williamse100ab52022-03-05 09:07:57 -070027 python3 -m venv $@ ;\
Zack Williams98fe2322021-09-20 15:02:11 -070028 source $@/bin/activate ;\
29 pip install -r requirements.txt
30
Zack Williams98fe2322021-09-20 15:02:11 -070031# lint and link verification. linkcheck is part of sphinx
Zack Williamse100ab52022-03-05 09:07:57 -070032test: license doc8 dict-check spelling linkcheck
Zack Williams98fe2322021-09-20 15:02:11 -070033
Zack Williamse100ab52022-03-05 09:07:57 -070034doc8: $(VENV_NAME)
Zack Williams98fe2322021-09-20 15:02:11 -070035 source $</bin/activate ; set -u ;\
Zack Williamse100ab52022-03-05 09:07:57 -070036 doc8 --ignore-path $< --ignore-path _build --ignore-path LICENSES --max-line-length 119
Zack Williams98fe2322021-09-20 15:02:11 -070037
Yi Tsengd6e23772022-03-01 16:31:55 -080038# Words in dict.txt must be in the correct alphabetical order and must not duplicated.
Zack Williamse100ab52022-03-05 09:07:57 -070039dict-check: sort-dict
40 @set -u ;\
41 git diff --exit-code dict.txt && echo "dict.txt is sorted" && exit 0 || \
42 echo "dict.txt is unsorted or needs to be added to git index" ; exit 1
Yi Tsengd6e23772022-03-01 16:31:55 -080043
Zack Williamse100ab52022-03-05 09:07:57 -070044sort-dict:
45 @sort -u < dict.txt > dict_sorted.txt
46 @mv dict_sorted.txt dict.txt
Yi Tsengd6e23772022-03-01 16:31:55 -080047
Zack Williams98fe2322021-09-20 15:02:11 -070048license: $(VENV_NAME)
49 source $</bin/activate ; set -u ;\
50 reuse --version ;\
51 reuse --root . lint
52
53# clean up
54clean:
55 rm -rf $(BUILDDIR)
56
57clean-all: clean
58 rm -rf $(VENV_NAME)
59
60# build multiple versions
Zack Williams015e1742022-03-08 11:26:24 -070061multiversion: $(VENV_NAME) Makefile
Zack Williams98fe2322021-09-20 15:02:11 -070062 source $</bin/activate ; set -u ;\
63 sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
64 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
65
66# Catch-all target: route all unknown targets to Sphinx using the new
67# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
Zack Williamse100ab52022-03-05 09:07:57 -070068%: $(VENV_NAME) Makefile
Zack Williams98fe2322021-09-20 15:02:11 -070069 source $</bin/activate ; set -u ;\
70 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)