Skip to content

Commit 9dffdc8

Browse files
satterlysatterly
committed
Use new sphinx theme and support markdown pages
1 parent f075ebe commit 9dffdc8

File tree

102 files changed

+630
-495
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

102 files changed

+630
-495
lines changed

‎.github/workflows/release.yml

+2-14
Original file line numberDiff line numberDiff line change
@@ -22,18 +22,6 @@ jobs:
2222
run:
2323
python3 -m pip install --upgrade pip
2424
pip install -r requirements.txt
25-
# - name: nitpick
26-
# id: nitpick
27-
# run:
28-
# sphinx-build -b html -n . _build/html
29-
# - name: linkcheck
30-
# id: linkcheck
31-
# run:
32-
# sphinx-build -b linkcheck . _build/linkcheck
33-
# - name: spelling
34-
# id: spelling
35-
# run:
36-
# sphinx-build -b spelling . _build/spelling
3725

3826
release:
3927
name: Publish
@@ -54,14 +42,14 @@ jobs:
5442
- name: Build HTML
5543
id: build
5644
run:
57-
sphinx-build -b html -d _build/doctrees . _build/html
45+
sphinx-build -b html source build
5846

5947
- name: Publish to GitHub Pages
6048
id: publish
6149
uses: peaceiris/actions-gh-pages@v3
6250
with:
6351
github_token: ${{ secrets.GITHUB_TOKEN }}
64-
publish_dir: _build/html
52+
publish_dir: build/html
6553

6654
- uses: act10ns/slack@v1
6755
with:

‎.github/workflows/tests.yml

+4-4
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,15 @@ jobs:
2020
- name: nitpick
2121
id: nitpick
2222
run:
23-
sphinx-build -b html -n . _build/html
23+
sphinx-build -n source build
2424
- name: linkcheck
2525
id: linkcheck
2626
run:
27-
sphinx-build -b linkcheck . _build/linkcheck
27+
sphinx-build -M linkcheck source build
2828
- name: spelling
2929
id: spelling
3030
run:
31-
sphinx-build -b spelling . _build/spelling
31+
sphinx-build -b spelling source build/spelling
3232

3333
build:
3434
runs-on: ubuntu-latest
@@ -41,4 +41,4 @@ jobs:
4141
- name: build
4242
id: build
4343
run:
44-
sphinx-build -b html -d _build/doctrees . _build/html
44+
sphinx-build -M html source build

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
*.pyc
44
venv/
55

6+
build/
67
_build/
78

‎.readthedocs.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ version: 2
66
build:
77
os: ubuntu-20.04
88
tools:
9-
python: "3.9"
9+
python: "3.11"
1010

1111
sphinx:
1212
configuration: conf.py

‎Makefile

+15-178
Original file line numberDiff line numberDiff line change
@@ -1,185 +1,22 @@
1-
# Makefile for Sphinx documentation
1+
# Minimal makefile for Sphinx documentation
22
#
33

4-
# You can set these variables from the command line.
5-
SPHINXOPTS =
6-
SPHINXBUILD = venv/bin/sphinx-build
7-
SPHINXAUTOBUILD = venv/bin/sphinx-autobuild
8-
PAPER =
9-
BUILDDIR = _build
10-
11-
# User-friendly check for sphinx-build
12-
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
13-
$(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/)
14-
endif
15-
16-
# Internal variables.
17-
PAPEROPT_a4 = -D latex_paper_size=a4
18-
PAPEROPT_letter = -D latex_paper_size=letter
19-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
20-
# the i18n builder cannot share the environment and doctrees with the others
21-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
22-
23-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SPHINXAUTOBUILD = sphinx-autobuild
9+
SOURCEDIR = source
10+
BUILDDIR = build
2411

12+
# Put it first so that "make" without argument is like "make help".
2513
help:
26-
@echo "Please use \`make <target>' where <target> is one of"
27-
@echo " html to make standalone HTML files"
28-
@echo " dirhtml to make HTML files named index.html in directories"
29-
@echo " singlehtml to make a single large HTML file"
30-
@echo " pickle to make pickle files"
31-
@echo " json to make JSON files"
32-
@echo " htmlhelp to make HTML files and a HTML help project"
33-
@echo " qthelp to make HTML files and a qthelp project"
34-
@echo " devhelp to make HTML files and a Devhelp project"
35-
@echo " epub to make an epub"
36-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
37-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
38-
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
39-
@echo " text to make text files"
40-
@echo " man to make manual pages"
41-
@echo " texinfo to make Texinfo files"
42-
@echo " info to make Texinfo files and run them through makeinfo"
43-
@echo " gettext to make PO message catalogs"
44-
@echo " changes to make an overview of all changed/added/deprecated items"
45-
@echo " xml to make Docutils-native XML files"
46-
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
47-
@echo " linkcheck to check all external links for integrity"
48-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
49-
@echo " tree show directories with reST files"
50-
51-
clean:
52-
rm -rf $(BUILDDIR)/*
14+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
5315

54-
html:
55-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
56-
@echo
57-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
58-
59-
dirhtml:
60-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
61-
@echo
62-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
63-
64-
singlehtml:
65-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
66-
@echo
67-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
6820

6921
livehtml:
70-
$(SPHINXAUTOBUILD) -b html --re-ignore ".git/*" --open-browser --port 7000 $(ALLSPHINXOPTS) $(BUILDDIR)/html
71-
72-
pickle:
73-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
74-
@echo
75-
@echo "Build finished; now you can process the pickle files."
76-
77-
json:
78-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
79-
@echo
80-
@echo "Build finished; now you can process the JSON files."
81-
82-
htmlhelp:
83-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
84-
@echo
85-
@echo "Build finished; now you can run HTML Help Workshop with the" \
86-
".hhp project file in $(BUILDDIR)/htmlhelp."
87-
88-
qthelp:
89-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
90-
@echo
91-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
92-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
93-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/alerta.qhcp"
94-
@echo "To view the help file:"
95-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/alerta.qhc"
96-
97-
devhelp:
98-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
99-
@echo
100-
@echo "Build finished."
101-
@echo "To view the help file:"
102-
@echo "# mkdir -p $$HOME/.local/share/devhelp/alerta"
103-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/alerta"
104-
@echo "# devhelp"
105-
106-
epub:
107-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
108-
@echo
109-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
110-
111-
latex:
112-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
113-
@echo
114-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
115-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
116-
"(use \`make latexpdf' here to do that automatically)."
117-
118-
latexpdf:
119-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
120-
@echo "Running LaTeX files through pdflatex..."
121-
$(MAKE) -C $(BUILDDIR)/latex all-pdf
122-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
123-
124-
latexpdfja:
125-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
126-
@echo "Running LaTeX files through platex and dvipdfmx..."
127-
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
128-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
129-
130-
text:
131-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
132-
@echo
133-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
134-
135-
man:
136-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
137-
@echo
138-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
139-
140-
texinfo:
141-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
142-
@echo
143-
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
144-
@echo "Run \`make' in that directory to run these through makeinfo" \
145-
"(use \`make info' here to do that automatically)."
146-
147-
info:
148-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
149-
@echo "Running Texinfo files through makeinfo..."
150-
make -C $(BUILDDIR)/texinfo info
151-
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
152-
153-
gettext:
154-
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
155-
@echo
156-
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
157-
158-
changes:
159-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
160-
@echo
161-
@echo "The overview file is in $(BUILDDIR)/changes."
162-
163-
linkcheck:
164-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
165-
@echo
166-
@echo "Link check complete; look for any errors in the above output " \
167-
"or in $(BUILDDIR)/linkcheck/output.txt."
168-
169-
doctest:
170-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
171-
@echo "Testing of doctests in the sources finished, look at the " \
172-
"results in $(BUILDDIR)/doctest/output.txt."
173-
174-
xml:
175-
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
176-
@echo
177-
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
178-
179-
pseudoxml:
180-
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
181-
@echo
182-
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
183-
184-
tree:
185-
@tree -P "*.rst" -L 2
22+
$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎README.md

+8-5
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,14 @@ To update the docs website:
1717
$ git push
1818

1919

20-
Requirements
21-
------------
22-
23-
* ReadTheDocs: https://readthedocs.org/
24-
* Alabaster: https://github.com/bitprophet/alabaster
20+
References
21+
----------
22+
23+
* ReadTheDocs https://readthedocs.org/
24+
* RTD Theme https://sphinx-rtd-theme.readthedocs.io/en/stable/
25+
* Alabaster https://github.com/bitprophet/alabaster
26+
* Pygments syntax highlighter https://pygments.org/languages/
27+
* MyST Parser https://myst-parser.readthedocs.io/en/latest/intro.html
2528

2629
License
2730
-------

0 commit comments

Comments
 (0)