Enable the built-in Sphinx 'linkcheck' builder and
fix initial findings.
Add this as an opportunistic build target only. The process is
long, and false positives are common (mostly anchor-related
for some reason). There is also already a third-party
company-wide service in place. This builder however will lead
to better link hygiene as it is stricter (mostly for anchors).
It also records all redirects, which should eventually be
replaced by proper links.
Change-Id: Ibed74b9f820c17a5984a78f4f61153e0499453fa
Make building of the guide quicker by adding to both the
'docs' and 'spelling' build targets:
* take advantage of multiprocessor hosts (add `-j auto`)
* only build pages that have changed (remove `-a`)
Change-Id: Ib31d505508d8dbfa08f8320605b9e50cacd8d764
To conform to documentation best practices add a
spellchecker. A Sphinx extension is used.
Correct any current spelling mistakes across the
doc set.
Add a seeding file that extends the system dictionary.
Going forward, the 'spelling_words.txt' file will
be used to extend the dictionary.
Do not enforce spelling during a normal doc build; add
a new tox target.
Add a non-voting Zuul job that consumes the new tox
target.
The doc-contrib documentation will include information
on the spellchecker in a subsequent PR.
Future work is necessary in terms of making checking more
intelligent. As such, file 'dubious_words.txt' has been
added to temporarily store those words that should be
filtered. For instance, the word 'tis' is in this file
because it is part of proper noun 'tpm-tis'. Hyphenated
words (or words in single quotes) could be exempt from
the check.
Change-Id: I70a1d5208b97923c081b359af3208f4de65eb6ca
Refactor the charm guide to have a Diataxis framework alignment. This
organizes the set of documentation into a variety of categories such as
getting started, how-tos, concepts, and reference material.
Change-Id: I7981ff6ac4b543020bfa78f352843370fcf09173
publish-openstack-sphinx-docs jobs are obsolete since some time,
use the newer publish-openstack-docs-pti jobs instead.
Update tox.ini to use the PTI way of building docs.
Fix all RST errors found so that this builds cleanly now.
Change-Id: I61dd9c0a2caa1b2e0c5e71c609091b7bb356520a
They essentially now say: use mypy types if you can, and even better
to use mypy type annotations.
Change-Id: I86da92cd480ae280f2f2f8c72b399a5e49903a86