100 lines
3.2 KiB
Makefile
100 lines
3.2 KiB
Makefile
# Makefile for Sphinx documentation
|
|
|
|
# You can set these variables from the command line, and also
|
|
# from the environment for the first two.
|
|
SPHINXOPTS ?=
|
|
SPHINXBUILD ?= sphinx-build
|
|
SOURCEDIR = .
|
|
BUILDDIR = _build
|
|
|
|
# Put it first so that "make" without argument is like "make help".
|
|
help:
|
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
|
|
.PHONY: help Makefile
|
|
|
|
# Install documentation dependencies
|
|
install:
|
|
pip install -r requirements.txt
|
|
|
|
# Build HTML documentation
|
|
html:
|
|
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
|
|
@echo
|
|
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
|
|
|
# Build PDF documentation using rst2pdf
|
|
pdf:
|
|
@$(SPHINXBUILD) -b pdf "$(SOURCEDIR)" "$(BUILDDIR)/pdf" $(SPHINXOPTS) $(O)
|
|
@echo
|
|
@echo "Build finished. The PDF file is in $(BUILDDIR)/pdf."
|
|
|
|
# Build PDF documentation using LaTeX
|
|
latexpdf:
|
|
@$(SPHINXBUILD) -b latex "$(SOURCEDIR)" "$(BUILDDIR)/latex" $(SPHINXOPTS) $(O)
|
|
@echo "Running LaTeX files through pdflatex..."
|
|
$(MAKE) -C "$(BUILDDIR)/latex" all-pdf
|
|
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
|
|
|
# Build EPUB documentation
|
|
epub:
|
|
@$(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)/epub" $(SPHINXOPTS) $(O)
|
|
@echo
|
|
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
|
|
|
# Build all formats
|
|
all: html pdf epub
|
|
@echo "All documentation formats built successfully."
|
|
|
|
# Clean build directory
|
|
clean:
|
|
rm -rf $(BUILDDIR)/*
|
|
@echo "Build directory cleaned."
|
|
|
|
# Development server with auto-reload
|
|
serve:
|
|
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" --host 0.0.0.0 --port 8080 --open-browser
|
|
|
|
# Check for broken links
|
|
linkcheck:
|
|
@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS) $(O)
|
|
@echo
|
|
@echo "Link check complete; look for any errors in the above output " \
|
|
"or in $(BUILDDIR)/linkcheck/output.txt."
|
|
|
|
# Check for spelling errors (requires sphinxcontrib-spelling)
|
|
spelling:
|
|
@$(SPHINXBUILD) -b spelling "$(SOURCEDIR)" "$(BUILDDIR)/spelling" $(SPHINXOPTS) $(O)
|
|
@echo
|
|
@echo "Spell check complete; look for any errors in the above output " \
|
|
"or in $(BUILDDIR)/spelling/."
|
|
|
|
# Build API documentation only
|
|
api-docs:
|
|
sphinx-apidoc -o api ../hcfs --force --separate
|
|
@echo "API documentation generated."
|
|
|
|
# Full rebuild (clean + build)
|
|
rebuild: clean html
|
|
@echo "Full rebuild complete."
|
|
|
|
# Check documentation coverage
|
|
coverage:
|
|
@$(SPHINXBUILD) -b coverage "$(SOURCEDIR)" "$(BUILDDIR)/coverage" $(SPHINXOPTS) $(O)
|
|
@echo
|
|
@echo "Coverage check complete; look for any missing documentation " \
|
|
"in $(BUILDDIR)/coverage/."
|
|
|
|
# Generate documentation statistics
|
|
stats:
|
|
@echo "Documentation Statistics:"
|
|
@echo "========================="
|
|
@find . -name "*.rst" -type f | wc -l | xargs echo "RST files:"
|
|
@find . -name "*.md" -type f | wc -l | xargs echo "Markdown files:"
|
|
@find . -name "*.py" -path "../hcfs/*" -type f | wc -l | xargs echo "Python files:"
|
|
@wc -l `find . -name "*.rst" -type f` | tail -1 | xargs echo "Total RST lines:"
|
|
|
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
|
%: Makefile
|
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|