Skip to content

Clean up documentation site #148

@sarayourfriend

Description

@sarayourfriend

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:

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions