blob: ae3fa4f2da0ffe74964bdf3dca16a66832c49b9d [file] [log] [blame]
Zack Williams7d058a92022-03-08 14:50:08 -07001# SPDX-FileCopyrightText: 2021 Open Networking Foundation <info@opennetworking.org>
2# SPDX-License-Identifier: Apache-2.0
3
Zack Williamsccaa38a2021-11-16 15:36:05 -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
16VENV_NAME := venv-docs
17
Zack Williams7d058a92022-03-08 14:50:08 -070018.PHONY: help Makefile test doc8 dict-check sort-dict license clean clean-all
Zack Williamsccaa38a2021-11-16 15:36:05 -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 Williams7d058a92022-03-08 14:50:08 -070027 python3 -m venv $@ ;\
Zack Williamsccaa38a2021-11-16 15:36:05 -070028 source $@/bin/activate ;\
29 pip install -r requirements.txt
30
Zack Williamsccaa38a2021-11-16 15:36:05 -070031# lint and link verification. linkcheck is part of sphinx
Zack Williams7d058a92022-03-08 14:50:08 -070032test: license doc8 dict-check spelling linkcheck
Zack Williamsccaa38a2021-11-16 15:36:05 -070033
Zack Williams7d058a92022-03-08 14:50:08 -070034doc8: $(VENV_NAME)
Zack Williamsccaa38a2021-11-16 15:36:05 -070035 source $</bin/activate ; set -u ;\
Zack Williams7d058a92022-03-08 14:50:08 -070036 doc8 --ignore-path $< --ignore-path _build --ignore-path LICENSES --max-line-length 119
37
38# Words in dict.txt must be in the correct alphabetical order and must not duplicated.
39dict-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
43
44sort-dict:
45 @sort -u < dict.txt > dict_sorted.txt
46 @mv dict_sorted.txt dict.txt
47
48license: $(VENV_NAME)
49 source $</bin/activate ; set -u ;\
50 reuse --version ;\
51 reuse --root . lint
Zack Williamsccaa38a2021-11-16 15:36:05 -070052
53# clean up
54clean:
55 rm -rf $(BUILDDIR)
56
57clean-all: clean
58 rm -rf $(VENV_NAME)
59
60# build multiple versions
Zack Williams7d058a92022-03-08 14:50:08 -070061multiversion: $(VENV_NAME) Makefile
Zack Williamsccaa38a2021-11-16 15:36:05 -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 Williams7d058a92022-03-08 14:50:08 -070068%: $(VENV_NAME) Makefile
Zack Williamsccaa38a2021-11-16 15:36:05 -070069 source $</bin/activate ; set -u ;\
70 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)