Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clean up documentation site #148

Open
2 of 3 tasks
sarayourfriend opened this issue Oct 15, 2024 · 0 comments
Open
2 of 3 tasks

Clean up documentation site #148

sarayourfriend opened this issue Oct 15, 2024 · 0 comments

Comments

@sarayourfriend
Copy link
Collaborator

sarayourfriend commented Oct 15, 2024

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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant