Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 1 | # Makefile for Sphinx documentation |
| 2 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 3 | # SPDX-FileCopyrightText: © 2020 Open Networking Foundation <support@opennetworking.org> |
| 4 | # SPDX-License-Identifier: Apache-2.0 |
| 5 | |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 6 | # use bash for pushd/popd, and to fail quickly |
| 7 | SHELL = bash -e -o pipefail |
| 8 | |
| 9 | # You can set these variables from the command line. |
Zack Williams | 1ae109e | 2021-07-27 11:17:04 -0700 | [diff] [blame] | 10 | SPHINXOPTS ?= -W |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 11 | SPHINXBUILD ?= sphinx-build |
| 12 | SOURCEDIR ?= . |
| 13 | BUILDDIR ?= _build |
| 14 | |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 15 | # Create the virtualenv with all the tools installed |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 16 | VENV_NAME := venv-docs |
| 17 | |
| 18 | # Put it first so that "make" without argument runs "make help". |
| 19 | help: $(VENV_NAME) |
| 20 | source ./$(VENV_NAME)/bin/activate ; set -u ;\ |
| 21 | $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
| 22 | |
| 23 | .PHONY: help Makefile test doc8 dict-check sort-dict license clean clean-all |
| 24 | |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 25 | $(VENV_NAME): |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 26 | python3 -m venv $@ ;\ |
| 27 | source ./$@/bin/activate ;\ |
| 28 | pip install -r requirements.txt |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 29 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 30 | # test - check that local build will lint, spelling is correct, then |
| 31 | # build the html site. |
| 32 | test: license doc8 dict-check spelling linkcheck |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 33 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 34 | # lint all .rst files |
| 35 | doc8: $(VENV_NAME) |
| 36 | source ./$</bin/activate ; set -u;\ |
| 37 | doc8 --ignore-path $< --ignore-path _build --ignore-path LICENSES --max-line-length 119 |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 38 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 39 | # Words in dict.txt must be in the correct alphabetical order and must not duplicated. |
| 40 | dict-check: sort-dict |
| 41 | @set -u ;\ |
| 42 | git diff --exit-code dict.txt && echo "dict.txt is sorted" && exit 0 || \ |
| 43 | echo "dict.txt is unsorted or needs to be added to git index" ; exit 1 |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 44 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 45 | sort-dict: |
| 46 | @sort -u < dict.txt > dict_sorted.txt |
| 47 | @mv dict_sorted.txt dict.txt |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 48 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 49 | license: $(VENV_NAME) ## Check license with the reuse tool |
| 50 | source ./$</bin/activate ; set -u ;\ |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 51 | reuse --version ;\ |
| 52 | reuse --root . lint |
| 53 | |
| 54 | # clean up |
| 55 | clean: |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 56 | rm -rf "$(BUILDDIR)" |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 57 | |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 58 | # clean-all - delete the virtualenv too |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 59 | clean-all: clean |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 60 | rm -rf "$(VENV_NAME)" |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 61 | |
| 62 | # build multiple versions |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 63 | multiversion: $(VENV_NAME) Makefile |
Zack Williams | 7f708f8 | 2020-07-07 12:18:20 -0700 | [diff] [blame] | 64 | source $</bin/activate ; set -u ;\ |
| 65 | sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS) |
| 66 | cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html" |
| 67 | |
| 68 | # Catch-all target: route all unknown targets to Sphinx using the new |
| 69 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). |
Zack Williams | 44faef9 | 2022-03-08 22:07:49 -0700 | [diff] [blame] | 70 | %: $(VENV_NAME) Makefile |
| 71 | source ./$</bin/activate ; set -u;\ |
| 72 | $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |