Maintainers Notes#

Information relevant for package maintenance

This section covers how to build the documentation#

  1. Tech stack for the documentation

  2. Information resources

  3. Processes for generating the HTML pages for readthedocs

  4. Processes for generating the markdown for the api documentation

  5. What to update, when and why

1. Summary of the tech stack#

scores utilises:

  • Sphinx, with the myst parts, for making the HTML pages

  • Markdown files as the text source for all the documentation

  • Myst Parser to enable Sphinx to utilise the markdown syntax

  • The ‘sphinx book’ theme for Sphinx

2. Useful information resources are:#

3. Process to generate the HTML pages#

  • sphinx-build -b html docs/ htmldocs is the key command to rebuild the HTML documentation from current sources

  • This requires docs/conf.py to be configured appropriately

4. Generating the markdown for the API documentation#

  • Each function must be added explicitly to api.md. The autogeneration tools are not sophisticated enough to process the import structure used to define the public API neatly

5. What to update, when and why#

what

when

why

README

a new is score added

README does not read from summary_table_of_scores.md

summary_table_of_scores

a new is score added

The rest of the docs includes this in various spots

api.md

a new function is added

Each function must be added individually