-
Notifications
You must be signed in to change notification settings - Fork 43
Open
Description
Pook's documentation site has several problems that need to be addressed:
- The build process is complicated, and involves manually merging Sphinx-generated API docs with additional handwritten documentation. This makes it more difficult to understand and maintain the documentation over time.
- The build emits hundreds of warnings.
- The documentation includes links hard-coded to the latest docs, meaning the multi-version RTD site will incorrectly point across versions if you are not reading docs for the latest version. For example, see the links on this page for v1.4.3, which all point to
latest: https://pook.readthedocs.io/en/v1.4.3/api.html - There are various grammatical and orthographical errors that should be fixed to tidy up the documentation.
The first two mean it's difficult/impossible to currently validate the documentation in CI, which makes it harder to verify changes to the documentation as we go along.
It should be possible to address this in three stages:
- Clean up the build process and fix warnings and incorrect links in Improve docs build and fix warnings #150
- Add CI checks that check the docs build and disallow warnings in the output Improve docs build and fix warnings #150
- Add a spelling linter, correct errors, and proofread the documentation for any basic grammatical errors
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels