Add version number to the docs

[Michael-T-McCann]

As far as I can tell, our docs https://scico.readthedocs.io/en/latest/index.html give you only the hash of the commit that you are reading, e.g., "© Copyright 2020-2021, SCICO Developers Revision 8e30134. " at the bottom of each page.

It would be nice to report loud and clear which version of SCICO you are looking at docs for. Especially since if you pip install you will have an older version than https://scico.readthedocs.io/ points to by default.

[bwohlberg]

The version number is already included in the page title. I guess it wouldn't hurt to include in the footer too, since the title is very easy to overlook.

[Michael-T-McCann]

Trying to clarify the issue a bit.

User experience: I find the github for SCICO and install using the linked instructions. I then try to copy/paste code snippets from the docs and they complain about undefined symbols. Or I read the API Reference and it talks about classes that I don't see when I dir(scico). Or I find a cool example and look for the corresponding script in examples/scripts and it doesn't exist.

This is happening because readthedocs defaults to "latest" which I guess is the latest commit in the repo. But the other option in readthedocs is "stable". Which release is that? How does a user know they are reading the correct version of the docs for the SCICO they have installed?

[bwohlberg]

The "stable" version on readthedocs is the most recent release. I agree it would be nice if the version number were displayed more prominently than just in the page title, but changing that isn't entirely trivial. Perhaps changing the default version on readthedocs from "latest" to "stable" would be a straightforward (I hope) but useful step in addressing the user experience scenario you describe?

[bwohlberg]

Update: the switch to defaulting to "stable" is straightforward, and is now in effect.

[Michael-T-McCann]

Update: the switch to defaulting to "stable" is straightforward, and is now in effect.

Great! This seems like a big improvement and I trust you that going further is hard. I'm okay to close.

[bwohlberg]

For what it's worth:

• The package version number can be included in the docs by using the substitution |version|.
• The sphinx template mechanism can be used to configure a custom footer; some additional work is probably necessary to include the package version number.
• There is an open issue on readthedocs (Display actual version number (possibly a new feature request) readthedocs/readthedocs.org#4529) on including an actual version number instead of latest or stable.

We can discuss further if you think it's worth pursuing any of these, but otherwise please just close this issue.