Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 1 | # Makefile for Trellis documentation created with Sphinx |
| 2 | |
| 3 | # use bash for pushd/popd, and to fail quickly. virtualenv's activate |
| 4 | # has undefined variables, so no -u |
| 5 | SHELL = bash -e -o pipefail |
| 6 | |
| 7 | # You can set these variables from the command line. |
| 8 | SPHINXOPTS ?= |
| 9 | SPHINXBUILD ?= sphinx-build |
| 10 | SOURCEDIR ?= . |
| 11 | BUILDDIR ?= _build |
| 12 | |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 13 | VENV_NAME := doc_venv |
| 14 | |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 15 | # Put it first so that "make" without argument is like "make help". |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 16 | help: $(VENV_NAME) |
| 17 | source ./$(VENV_NAME)/bin/activate ;\ |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 18 | $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
| 19 | |
| 20 | .PHONY: help lint reload Makefile test |
| 21 | |
| 22 | # Create the virtualenv with all the tools installed |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 23 | $(VENV_NAME): |
| 24 | virtualenv -p python3 $(VENV_NAME) ;\ |
| 25 | source ./$(VENV_NAME)/bin/activate ;\ |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 26 | pip install -r requirements.txt |
| 27 | |
| 28 | # automatically reload changes in browser as they're made |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 29 | reload: $(VENV_NAME) |
| 30 | source $</bin/activate ; set -u ;\ |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 31 | sphinx-reload $(SOURCEDIR) |
| 32 | |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 33 | # build multiple versions |
| 34 | multiversion: $(VENV_NAME) Makefile |
| 35 | source $</bin/activate ; set -u ;\ |
| 36 | sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS) |
| 37 | cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html" |
| 38 | |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 39 | # lint and link verification. linkcheck is built into sphinx |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 40 | test: lint spelling linkcheck |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 41 | |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 42 | lint: doc8 |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 43 | |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 44 | doc8: $(VENV_NAME) | $(OTHER_REPO_DOCS) |
| 45 | source $</bin/activate ; set -u ;\ |
| 46 | doc8 --max-line-length 119 \ |
| 47 | $$(find . -name \*.rst ! -path "*venv*" ! -path "*vendor*" ! -path "*repos*" ) |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 48 | |
| 49 | # clean up |
| 50 | clean: |
| 51 | rm -rf $(BUILDDIR) |
| 52 | |
| 53 | clean-all: clean |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 54 | rm -rf $(VENV_NAME) |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 55 | |
| 56 | # Catch-all target: route all unknown targets to Sphinx using the new |
| 57 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). |
Zack Williams | d63d35b | 2020-06-23 14:12:46 -0700 | [diff] [blame] | 58 | %: $(VENV_NAME) | $(OTHER_REPO_DOCS) |
| 59 | source $</bin/activate ; set -u ;\ |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 60 | $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |