Skip to content

Commit 7f09cf9

Browse files
minrkminrk
authored
Merge pull request #805 from minrk/doc-lint
test docs on CI and fix lint
2 parents ea97c18 + cf333c7 commit 7f09cf9

19 files changed

+301
-786
lines changed

‎.github/workflows/test-docs.yml

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Test docs
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches-ignore:
7+
- "dependabot/**"
8+
- "pre-commit-ci-update-config"
9+
tags:
10+
- "**"
11+
workflow_dispatch:
12+
13+
env:
14+
# UTF-8 content may be interpreted as ascii and causes errors without this.
15+
LANG: C.UTF-8
16+
PYTEST_ADDOPTS: "--verbose --color=yes"
17+
18+
jobs:
19+
test-docs:
20+
runs-on: ubuntu-22.04
21+
steps:
22+
- uses: actions/checkout@v3
23+
with:
24+
# make rediraffecheckdiff requires git history to compare current
25+
# commit with the main branch and previous releases.
26+
fetch-depth: 0
27+
28+
- uses: actions/setup-python@v4
29+
with:
30+
python-version: "3.10"
31+
32+
- name: Install requirements
33+
run: |
34+
pip install -r docs/requirements.txt .
35+
36+
# readthedocs doesn't halt on warnings,
37+
# so raise any warnings here
38+
- name: build docs
39+
run: |
40+
cd docs
41+
make html
42+
43+
- name: check links
44+
run: |
45+
cd docs
46+
make linkcheck
47+
48+
# make rediraffecheckdiff compares files for different changesets
49+
# these diff targets aren't always available
50+
# - compare with base ref (usually 'main', always on 'origin') for pull requests
51+
# - only compare with tags when running against main repo
52+
# to avoid errors on forks, which often lack tags
53+
- name: check redirects for this PR
54+
if: github.event_name == 'pull_request'
55+
run: |
56+
cd docs
57+
export REDIRAFFE_BRANCH=origin/${{ github.base_ref }}
58+
make rediraffecheckdiff
59+
60+
# this should check currently published 'stable' links for redirects
61+
- name: check redirects since last release
62+
if: github.repository == 'ipython/ipyparallel'
63+
run: |
64+
cd docs
65+
export REDIRAFFE_BRANCH=$(git describe --tags --abbrev=0)
66+
make rediraffecheckdiff
67+
68+
# longer-term redirect check (fixed version) for older links
69+
- name: check redirects since 8.6.0
70+
if: github.repository == 'ipython/ipyparallel'
71+
run: |
72+
cd docs
73+
export REDIRAFFE_BRANCH=8.6.0
74+
make rediraffecheckdiff

‎docs/Makefile

Lines changed: 41 additions & 181 deletions
Original file line numberDiff line numberDiff line change
@@ -1,194 +1,54 @@
1-
# Makefile for Sphinx documentation
2-
#
3-
4-
# You can set these variables from the command line.
5-
SPHINXOPTS =
6-
SPHINXBUILD = sphinx-build
7-
PAPER =
8-
BUILDDIR = build
1+
# Makefile for Sphinx documentation generated by sphinx-quickstart
2+
# ----------------------------------------------------------------------------
93

10-
# User-friendly check for sphinx-build
11-
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12-
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13-
endif
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?= --color -W --keep-going
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = _build
1410

15-
# Internal variables.
16-
PAPEROPT_a4 = -D latex_paper_size=a4
17-
PAPEROPT_letter = -D latex_paper_size=letter
18-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
19-
# the i18n builder cannot share the environment and doctrees with the others
20-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
2114

22-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
15+
.PHONY: help Makefile
2316

24-
default: html
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option.
19+
#
20+
# Several sphinx-build commands can be used through this, for example:
21+
#
22+
# - make clean
23+
# - make linkcheck
24+
# - make spelling
25+
#
26+
%: Makefile
27+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
2528

26-
help:
27-
@echo "Please use \`make <target>' where <target> is one of"
28-
@echo " html to make standalone HTML files"
29-
@echo " dirhtml to make HTML files named index.html in directories"
30-
@echo " singlehtml to make a single large HTML file"
31-
@echo " pickle to make pickle files"
32-
@echo " json to make JSON files"
33-
@echo " htmlhelp to make HTML files and a HTML help project"
34-
@echo " qthelp to make HTML files and a qthelp project"
35-
@echo " applehelp to make an Apple Help Book"
36-
@echo " devhelp to make HTML files and a Devhelp project"
37-
@echo " epub to make an epub"
38-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
39-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
40-
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
41-
@echo " text to make text files"
42-
@echo " man to make manual pages"
43-
@echo " texinfo to make Texinfo files"
44-
@echo " info to make Texinfo files and run them through makeinfo"
45-
@echo " gettext to make PO message catalogs"
46-
@echo " changes to make an overview of all changed/added/deprecated items"
47-
@echo " xml to make Docutils-native XML files"
48-
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
49-
@echo " linkcheck to check all external links for integrity"
50-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
51-
@echo " coverage to run coverage check of the documentation (if enabled)"
5229

53-
clean:
54-
rm -rf $(BUILDDIR)/*
30+
# Manually added targets - related to code generation
31+
# ----------------------------------------------------------------------------
5532

33+
# For local development:
34+
# - builds the html
35+
# - NOTE: If the pre-requisites for the html target is updated, also update the
36+
# Read The Docs section in docs/source/conf.py.
37+
#
5638
html:
57-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
39+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
5840
@echo
5941
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
6042

61-
dirhtml:
62-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
63-
@echo
64-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
65-
66-
singlehtml:
67-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
68-
@echo
69-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
70-
71-
pickle:
72-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
73-
@echo
74-
@echo "Build finished; now you can process the pickle files."
75-
76-
json:
77-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
78-
@echo
79-
@echo "Build finished; now you can process the JSON files."
80-
81-
htmlhelp:
82-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
83-
@echo
84-
@echo "Build finished; now you can run HTML Help Workshop with the" \
85-
".hhp project file in $(BUILDDIR)/htmlhelp."
86-
87-
qthelp:
88-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
89-
@echo
90-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
91-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
92-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPythonparallel.qhcp"
93-
@echo "To view the help file:"
94-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPythonparallel.qhc"
95-
96-
applehelp:
97-
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
98-
@echo
99-
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
100-
@echo "N.B. You won't be able to view it unless you put it in" \
101-
"~/Library/Documentation/Help or install it in your application" \
102-
"bundle."
103-
104-
devhelp:
105-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
106-
@echo
107-
@echo "Build finished."
108-
@echo "To view the help file:"
109-
@echo "# mkdir -p $$HOME/.local/share/devhelp/IPythonparallel"
110-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/IPythonparallel"
111-
@echo "# devhelp"
112-
113-
epub:
114-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
115-
@echo
116-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
117-
118-
latex:
119-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
120-
@echo
121-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
122-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
123-
"(use \`make latexpdf' here to do that automatically)."
124-
125-
latexpdf:
126-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
127-
@echo "Running LaTeX files through pdflatex..."
128-
$(MAKE) -C $(BUILDDIR)/latex all-pdf
129-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
130-
131-
latexpdfja:
132-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
133-
@echo "Running LaTeX files through platex and dvipdfmx..."
134-
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
135-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
136-
137-
text:
138-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
139-
@echo
140-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
141-
142-
man:
143-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
144-
@echo
145-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
146-
147-
texinfo:
148-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
149-
@echo
150-
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
151-
@echo "Run \`make' in that directory to run these through makeinfo" \
152-
"(use \`make info' here to do that automatically)."
15343

154-
info:
155-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
156-
@echo "Running Texinfo files through makeinfo..."
157-
make -C $(BUILDDIR)/texinfo info
158-
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
44+
# Manually added targets - related to development
45+
# ----------------------------------------------------------------------------
15946

160-
gettext:
161-
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
162-
@echo
163-
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
164-
165-
changes:
166-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
167-
@echo
168-
@echo "The overview file is in $(BUILDDIR)/changes."
169-
170-
linkcheck:
171-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
172-
@echo
173-
@echo "Link check complete; look for any errors in the above output " \
174-
"or in $(BUILDDIR)/linkcheck/output.txt."
175-
176-
doctest:
177-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
178-
@echo "Testing of doctests in the sources finished, look at the " \
179-
"results in $(BUILDDIR)/doctest/output.txt."
180-
181-
coverage:
182-
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
183-
@echo "Testing of coverage in the sources finished, look at the " \
184-
"results in $(BUILDDIR)/coverage/python.txt."
185-
186-
xml:
187-
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
188-
@echo
189-
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
190-
191-
pseudoxml:
192-
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
193-
@echo
194-
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
47+
# For local development:
48+
# - requires sphinx-autobuild, see
49+
# https://sphinxcontrib-spelling.readthedocs.io/en/latest/
50+
# - builds and rebuilds html on changes to source, but does not re-generate
51+
# metrics/scopes files
52+
# - starts a livereload enabled webserver and opens up a browser
53+
devenv: html
54+
sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html"

0 commit comments

Comments
 (0)