Commit Graph

8 Commits

Author SHA1 Message Date
Peter Matulis d2a9a6380a Add linkchecking
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
2022-09-18 12:20:20 -04:00
Peter Matulis 352c4ebb92 Improve build targets
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
2022-05-19 13:58:44 -04:00
Peter Matulis eb1e9e207b Add a spellchecker
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
2022-04-11 12:45:10 -04:00
Billy Olsen d0f3511d1f Refactor Charm Guide
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
2021-10-04 20:38:11 -07:00
Peter Matulis 9e8aad5902 Update doc tools for the charm guide
This is based on a similar PR for the deploy-guide:

https://review.opendev.org/#/c/691241

Closes-Bug: #1808312

Change-Id: I4bff68c5103fe47407e449ad4717f4fd0f320fcf
2019-10-29 10:12:02 -04:00
Andreas Jaeger ccdcae52be Update docs job
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
2019-05-19 14:06:57 +02:00
Alex Kavanagh 98636ad53f Update coding standards to improved docstrings for Py3
They essentially now say: use mypy types if you can, and even better
to use mypy type annotations.

Change-Id: I86da92cd480ae280f2f2f8c72b399a5e49903a86
2018-07-23 12:44:32 +01:00
James Page cf6a5a2e15 Initial baseline of OpenStack Charm documentation 2016-06-20 11:59:38 +01:00