search

nextstrain / sphinx-theme

A Sphinx theme for Nextstrain's documentation, based on Read The Docs' default theme.
https://docs.nextstrain.org/projects/sphinx-theme/
MIT License
0 stars 5 forks source link

Show precise versions for stable and development ("latest") #16

Closed tsibley closed 2 years ago

tsibley commented 2 years ago

Make it even clearer what software revisions those labels represent.

A git describe style string[^1] for development ("latest") would be even better than just the git revision, but that appears to be non-trivial to implement.

Resolves https://github.com/nextstrain/augur/issues/817.

h/t to @corneliusroemer for the suggestion and @huddlej for bringing it up again in https://github.com/nextstrain/sphinx-theme/pull/15.

[^1]: e.g. "${tag}-${n}-g${sha}" where ${tag} is the last/closest tag to the current commit, ${n} is the number of commits since that ${tag}, and ${sha} is the shortened id of the current commit.

tsibley commented 2 years ago

Examples:

https://readthedocs-testbed.readthedocs.io/en/stable/ image

https://readthedocs-testbed.readthedocs.io/en/latest/ image

https://readthedocs-testbed.readthedocs.io/en/20220128.1/ image

tsibley commented 2 years ago

Yeah, https://github.com/nextstrain/readthedocs-testbed and https://readthedocs-testbed.readthedocs.org are new to test out this PR (but I expect to find use for them in future work too).

These changes should work across our real projects with one caveat: the precise version in "stable version (X)" can only be shown if the project's Sphinx conf.py sets a version. Without a version, it'll just display "stable version".

Augur currently doesn't define version, but that can be fixed easily enough. The theme also won't break if version is missing, so it's safe to merge and release this theme change before we go update Augur and others.