diff --git a/Makefile b/Makefile index dcf383a4..901e0ff8 100644 --- a/Makefile +++ b/Makefile @@ -5,19 +5,28 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build +SPHINXDIR = .sphinx SOURCEDIR = . BUILDDIR = _build -VENV = .sphinx/venv/bin/activate +VENVDIR = $(SPHINXDIR)/venv +VENV = $(VENVDIR)/bin/activate # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -install: +.PHONY: help + +# Explicit target avoids fall-through to the "Makefile" target. +$(SPHINXDIR)/requirements.txt: + test -f $(SPHINXDIR)/requirements.txt + +# If requirements are updated, venv should be rebuilt and timestamped. +$(VENVDIR): $(SPHINXDIR)/requirements.txt @echo "... setting up virtualenv" - python3 -m venv .sphinx/venv - . $(VENV); pip install --upgrade -r .sphinx/requirements.txt + python3 -m venv $(VENVDIR) + . $(VENV); pip install --upgrade -r $(SPHINXDIR)/requirements.txt @echo "\n" \ "--------------------------------------------------------------- \n" \ @@ -26,40 +35,77 @@ install: "* only serve: make serve \n" \ "* clean built doc files: make clean-doc \n" \ "* clean full environment: make clean \n" \ - "* check spelling: make spelling \n" \ + "* check spelling: make spelling \n" \ "* check inclusive language: make woke \n" \ + "* other possible targets: make \n" \ "--------------------------------------------------------------- \n" -run: + @touch $(VENVDIR) + + +install: $(VENVDIR) + +.PHONY: install + + +run: install . $(VENV); sphinx-autobuild -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -html: +.PHONY: run + +# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. +html: install . $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt -epub: +.PHONY: html + + +epub: install . $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt -serve: +.PHONY: epub + + +serve: html cd "$(BUILDDIR)"; python3 -m http.server 8000 +.PHONY: serve + + clean: clean-doc - rm -rf .sphinx/venv + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + rm -rf $(VENVDIR) + +.PHONY: clean + clean-doc: git clean -fx "$(BUILDDIR)" +.PHONY: clean-doc + + spelling: html . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml -linkcheck: +.PHONY: spelling + + +linkcheck: install . $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" +.PHONY: linkcheck + + woke: type woke >/dev/null 2>&1 || { sudo snap install woke; } woke *.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml -.PHONY: help Makefile +.PHONY: woke + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: Makefile