| # Makefile for Sphinx documentation |
| |
| PYTHON = python3 |
| PYTHONWARNINGS = always,ignore:::sphinx_sitemap,ignore:::matplotlib.projections,ignore:::notfound.extension |
| SPHINXBUILD = PYTHONWARNINGS="$(PYTHONWARNINGS)" $(PYTHON) -m sphinx |
| SPHINXAUTOBUILD = PYTHONWARNINGS="$(PYTHONWARNINGS)" sphinx-autobuild |
| SPHINXOPTS = --fail-on-warning --jobs=auto |
| BUILDDIR = _build |
| DOCTREES = $(BUILDDIR)/doctrees |
| OUTDIR = $(BUILDDIR)/html |
| DIRHTML = -b dirhtml -d $(DOCTREES) . $(OUTDIR) |
| # "make autoreload" gets its own dir. Sharing one with the other targets makes |
| # them delete files from under each other. |
| LIVEDIR = $(BUILDDIR)/live |
| LIVE_DIRHTML = -b dirhtml -d $(LIVEDIR)/doctrees . $(LIVEDIR)/html |
| |
| # --- build |
| |
| clean: ## Remove all build files |
| rm -rf $(BUILDDIR) |
| |
| html: ## Generate doc in HTML format. Warnings are turned into failures. |
| $(SPHINXBUILD) $(SPHINXOPTS) $(DIRHTML) |
| |
| autoreload: ## Rebuild HTML + live-reload browser on file changes (requires sphinx-autobuild) |
| $(SPHINXAUTOBUILD) $(SPHINXOPTS) $(LIVE_DIRHTML) |
| |
| autoreload-hard: ## Same as above but re-writes all files on every refresh |
| rm -rf $(LIVEDIR) |
| $(SPHINXAUTOBUILD) $(SPHINXOPTS) -a $(LIVE_DIRHTML) |
| |
| versions: ## Build past doc releases into the current build (needs `html` first) |
| $(PYTHON) ../scripts/internal/docs/build_versions.py $(OUTDIR) |
| |
| # --- checkers |
| |
| check-links: ## Check links. Prints only broken URLs / warnings. |
| $(SPHINXBUILD) $(SPHINXOPTS) --quiet -b linkcheck -d $(DOCTREES) . $(BUILDDIR)/linkcheck |
| @echo "Link check complete; full report in $(BUILDDIR)/linkcheck/output.txt." |
| |
| check-codeautolink: ## Report sphinx-codeautolink resolution failures (non-fatal). |
| $(SPHINXBUILD) --jobs=auto \ |
| -D codeautolink_warn_on_failed_resolve=1 \ |
| -D codeautolink_warn_on_missing_inventory=1 \ |
| -b dirhtml -d $(BUILDDIR)/codeautolink/doctrees . $(BUILDDIR)/codeautolink/html |
| |
| # --- tests |
| |
| test: ## Run doc sanity tests. |
| $(PYTHON) -m pytest test_docs.py $(ARGS) |
| |
| test-online-doc: ## Smoke tests against the live docs site. |
| PSUTIL_DOCS_ONLINE=1 $(PYTHON) -m pytest test_docs_online.py -v |
| |
| # --- tools |
| |
| blog-post: ## Create a new blog post skeleton |
| @test -n "$(SLUG)" || { echo "Usage: make blog-post SLUG=<slug> [TITLE=<text>] [TAGS=<csv>]"; exit 1; } |
| $(PYTHON) ../scripts/internal/docs/new_blog_post.py "$(SLUG)"$(if $(TITLE), --title "$(TITLE)")$(if $(TAGS), --tags "$(TAGS)") |
| |
| refresh-adoption-stats: ## Refresh PyPI/GitHub stats in adoption.rst and README.rst |
| $(PYTHON) ../scripts/internal/docs/refresh_adoption_stats.py |
| $(MAKE) -C .. fix-rst |
| |
| help: ## Display callable targets. |
| @awk -F':.*?## ' '/^[a-zA-Z0-9_.-]+:.*?## / {printf "\033[36m%-24s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort |
