docs: python-tuf version should be visible in docs (readthedocs)

[jku]

https://theupdateframework.readthedocs.io/en/stable/ works great and automatically updates based on release tags.

But it's hard to see which release the docs are actually for...

I'm not sure if the solution is to build the version number into the main documentation page, or if there's a readthedocs feature we could use to have the tag name visible in the UI?

[sechkova]

Why not activating a version build from a tag?

https://theupdateframework.readthedocs.io/en/v0.18.1/
https://readthedocs.org/projects/theupdateframework/versions/

I had to manually go to Versions and click the "Activate" button.

[jku]

Yeah that helps... At least from release notes and such we can link to specific versions. https://docs.readthedocs.io/en/stable/automation-rules.html shows that we can make the activation automatic as well: I'll try it.

So maybe it doesn't matter that https://theupdateframework.readthedocs.io/en/latest/ doesn't say anywhere which version it is?

[sechkova]

So maybe it doesn't matter that https://theupdateframework.readthedocs.io/en/latest/ doesn't say anywhere which version it is?

latest or stable? I think I'm ok with it but other options that come to my mind is hiding stable and using the "tag" version only or setting the "tag" one as default.

[jku]

latest or stable?

Right, I meant "stable" as the problematic one (but would be nice if "latest" was clearly marked as git version as well).

[lukpueh]

Just found the corresponding upstream issue: readthedocs/readthedocs.org#4529.
I think implementing any of the workarounds mentioned there in would go a long way.

[ashwin0630]

hey I'm interested to work in this issue is this still open!!

[jku]

Sure, thanks. tox -e docs will run the docs build locally so you can try things out.

https://www.sphinx-doc.org/en/master/usage/configuration.html says that variable version can be defined in conf.py and then that can be used as a substitution |version| in the docs.

Maybe you can just import tuf and version = tuf.__version__ in conf.py? Worth trying out

[ashwin0630]

i get an attribute error tuf has no attribute version

[jku]

Please link to a branch with the changes (that do not work) if you'd like someone to have a look

[gkum99]

@jku
Hello, I have set up the environment and was trying out your suggestion about setting up version = tuf.__version__. How do I test this?

[jku]

Hello, I have set up the environment and was trying out your suggestion about setting up version = tuf.__version__. How do I test this?

I mentioned this a few posts up:

tox -e docs will run the docs build locally so you can try things out.

Results in docs/build if I recall correctly

[gkum99]

@jku
I get the following results, is this what you expect?

[jku]

You don't mention what changed so I don't know... but if docs build from 'develop' does not include the version and a build with your change does, then that seems like a good sign that it will work similarly on readthedocs.

Feel free to do a PR so we get a docs build on readthedocs.

Possible further improvements:

1. Could include the version string in the intro text as well (using |version| in docs/index.rst)
2. We could start using development versions so the version number in the docs would reflect that this is documentation for an unreleased python-tuf

You can not fix the second issue (it's a release process fix), but if you want you can try the first one. It's not required though, a PR with the version setting is fine.

[gkum99]

@jku i have raised a pull request. kindly review it.

[jku]

I'm reopening: The change seems fine but readthedocs does something on their end that hides this change https://theupdateframework.readthedocs.io/en/latest/index.html

I think we can still try using the version in the actual documentation content: if that doesn't work then this is just not worth this much work.

[abhiii71]

Hey @jku, Am totally new here don't know how to work on this issue,but want to contribute (getting started ). So can you please guide me. Thank you !!!