blob: 79f2f4b221cd3b4b584d4e130fadf3f1e76141c0 [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
16VENV_NAME := venv-docs
17
Yi Tsengd6e23772022-03-01 16:31:55 -080018.PHONY: help test lint doc8 reload Makefile prep format format-dict
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):
27 python3 -m venv $(VENV_NAME) ;\
28 source $@/bin/activate ;\
29 pip install -r requirements.txt
30
31# automatically reload changes in browser as they're made
32reload: $(VENV_NAME)
33 source $</bin/activate ; set -u ;\
34 sphinx-reload $(SOURCEDIR)
35
36# lint and link verification. linkcheck is part of sphinx
Yi Tsengd6e23772022-03-01 16:31:55 -080037test: lint spelling linkcheck dict-check
Zack Williams98fe2322021-09-20 15:02:11 -070038
39lint: doc8
40
41doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS)
42 source $</bin/activate ; set -u ;\
43 doc8 --max-line-length 119 \
44 $$(find . -name \*.rst ! -path "*venv*" ! -path "*vendor*" ! -path "*repos*" )
45
Yi Tsengd6e23772022-03-01 16:31:55 -080046# Words in dict.txt must be in the correct alphabetical order and must not duplicated.
47dict-check: format-dict
48 @git update-index --refresh
49
50format: format-dict
51
52format-dict:
53 @cat dict.txt | sort -u > /tmp/sorted.txt
54 @mv /tmp/sorted.txt dict.txt
55
Zack Williams98fe2322021-09-20 15:02:11 -070056license: $(VENV_NAME)
57 source $</bin/activate ; set -u ;\
58 reuse --version ;\
59 reuse --root . lint
60
61# clean up
62clean:
63 rm -rf $(BUILDDIR)
64
65clean-all: clean
66 rm -rf $(VENV_NAME)
67
68# build multiple versions
69multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
70 source $</bin/activate ; set -u ;\
71 sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
72 cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
73
74# Catch-all target: route all unknown targets to Sphinx using the new
75# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
76%: $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
77 source $</bin/activate ; set -u ;\
78 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)