Maintainers Notes

Maintainers Notes#

Information relevant for package maintenance

This section covers the process for making a release from the develop branch#

  1. Run through the notebooks manually

  2. Run the unit tests

  3. Prepare the merge request in github (do not do a rebase merge to main – do a regular merge commit)

  4. Check readthedocs rebuilds correctly, including manually checking the version number looks right

  5. Perform the merge to main

  6. Build a new environment and perform basic testing on main

  7. Update github with a tagged release

  8. Prepare the package files (see below)

  9. Prepare the PyPI update (should move to a Github Action)

  10. Perform the PyPI update (should move to a Github Action)

Test the new main branch#

  1. Create a new virtual environment

  2. Make sure you check out the ‘main’ branch

  3. Install scores[all]

  4. Run the tests again, just for surety

Update GitHub with a tagged release#

  1. Click on the ‘releases’ area of the front page

  2. Follow the ‘create release’ workflow, and create a tag at the same time

Create the package files locally#

  1. Install scores[maintainer]

  2. Run pytest again

  3. Run ‘hatch build’. This will make the release files (sdist and wheel).

Update PyPI manually#

  1. Run python3 -m keyring –disable

  2. Run hatch publish -r test

  3. Create a new virtual env, and install the test scores with python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple scores

  4. Do a little manual testing

  5. Run hatch publish

  6. Uninstall the test scores, re-install the now-updated package, do a little testing

This section covers how to build the documentation locally#

(Readthedocs should update automatically from a GitHub Action)

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

  • Pandoc should be installed through the OS package manager separately

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 score is added

in case it deserves a mention

api.md

a new function is added

each function must be added individually

included.md

a new function is added

each function (and each variation of the function name) must be added individually

Tutorial_Gallery.ipynb

a new tutorial is added

navigation throughout the docs

This section covers checking the documentation renders properly in readthedocs#

What documentation needs checking in readthedocs#

Each time an existing function is modified or a new function is added to scores, the rendering in readthedocs for any modified or newly created documentation must be checked.

This applies to each of the following documents:

  • included.md

  • API Documentation

  • Tutorials (see also tutorial rendering further below)

  • (If applicable) README

Common rendering issues in readthedocs#

Frequent issues include:

  • Lists (including lists that use bullets, dot points, hyphens, numbers, letters etc.)

    • Check each list appears and renders properly

    • Check all indented lists/sub-lists for proper indentation

  • Figures: check each figure appears and renders properly

  • Plots: check each plot appears and renders properly

  • Tables: check each table appears and renders properly

  • Formulae: check each formula appears and renders properly

  • API Documentation: in addition to checking the above items, also confirm “Returns” and “Return Type” are rendering as expected

Tutorial rendering#

Things that render well in JupyterLab do not always render properly in readthedocs. Additionally, fixes that work well when built locally, don’t always work when merged into the codebase.

To check the rendering of tutorials in readthedocs:

  • Compare the tutorial in readthedocs against a version running in JupyterLab (as not everything renders in GitHub).

  • Check the entirety of the tutorial (sometimes things will render properly in one section, while not rendering properly in a different section of the same tutorial).

  • If you make any changes to the code cells, re-execute the Notebook in JupyterLab before committing, otherwise some things (e.g. some plots) won’t render in readthedocs. Then re-check the tutorial in readthedocs to ensure the tutorial is still rendering properly.

Ideally, also check the tutorial renders properly in nbviewer (there is a link at the top of each tutorial page in readthedocs).

Contents