Documentation update and versioning

[ajstewart]

This brings the documentation up-to-date in using the latest mkdocs-material release. It also adds docs versioning so the docs can be viewed for each release, in addition to the dev version.

• Updates all docs related packages.
• Added the mike dependency for versioning.
• mkdocstrings updated to use new python handler Griffe, this fixes #486.
  • serializers.py and views.py are now shown in the code reference.
• Updated Returns: docstrings to follow new handling of Tuple or Union return types.
• Updated GitHub actions to:
  • Build and publish dev docs on each push to dev.
  • Build and publish new release docs upon the publication of a release.
• Minor updates to mkdocs setup to be compatible with move from 7.x -> 8.x.
• Minor docstring fixes.

Note:

• The Griffe handler doesn't currently support selection, so all previous 'hidden' functions are now shown in the Code Reference section. These might be missing docstrings. Suggest opening issue to either fill these in or re-hide them once Griffe supports that option.

Before Merging

• [x] Manually clear current gh-pages branch using mike.
• [x] Manually checkout and upload v1.0.0 docs.
• [x] Fix versioning link errors.

Fixes #486.

[ajstewart]

After testing the deployment there are two errors that need tracking down:

• Outdated banner does not construct the link correctly, as base_url contains the full path.
• 8.2.1 should allow 'switch to current page' and fall back to the homepage if pages are missing. However currently these 404.

The v1.0.0 docs are using quite an old version of mkdocs-material so that might also complicate things.

I've converted to a draft while I investigate.

[ajstewart]

After testing the deployment there are two errors that need tracking down:

• Outdated banner does not construct the link correctly, as base_url contains the full path.
• 8.2.1 should allow 'switch to current page' and fall back to the homepage if pages are missing. However currently these 404.

The v1.0.0 docs are using quite an old version of mkdocs-material so that might also complicate things.

I've converted to a draft while I investigate.

@marxide if you want a puzzle...

Everything here appears to be working expect for the banner links and page diverting when changing versions. But it is only breaking when the initial page load is on the homepage. If you visit the docs from any other page directly, e.g.

localhost:8008/dev/developing/intro/

Then you can browse around the website the outdated banner has the correct link and any new pages that don't exist in the old docs redirect to the homepage as expected.

If you start directly on the homepage then all the links muck up. Which is really strange as the base_url parameter seems to work correctly in the announcement bar message for that link, but not in the outdated block which is right below it.

I tested a brand new simple mkdocs-material project, put all our overrides in and I could not replicate the error so I must be missing something somewhere.

p.s. I test it by deploying the same version twice with a different tag, i.e.:

mike deploy v1.0
mike deploy v2.0

[ajstewart]

A new release of mkdocs-material should fix the above problems.

Will wait for a release based off the fix mentioned here: https://github.com/squidfunk/mkdocs-material/issues/3653.

[ajstewart]

@marxide this is now ready with the release of mkdocs-material 8.2.4.

So it doesn't break everything as it's on an old version, I manually made it so the v1.0.0 release docs could be built on the latest docs versions (i.e. this branch). This will result in some of the code reference being a bit dodgy, but all the fixes from this one will be present in the next release. The v1.0.0 docs will never have to be touched again.

I have deployed this version as is along with the mentioned v1.0.0: https://www.vast-survey.org/vast-pipeline/ everything should be working!

The git actions will just have to be tested after this is merged and correct any mistakes then.