feat: add docs_version configuration for RTD publications

[stichbury]

Summary

For docs that publish to versioned paths, it isn't sufficient to use the site_url path to build URLs for llms.txt because that will always default to one version, mostly stable. That means the llms.txt will build linkes for each file that point to stable. For older versions, this doesn't work, since it means the llms.txt gets out of sync, and points into docs for current stable builds, rather than the build they actually accompany.

We cannot rely on updating site_url to set it to a particular version for each build either, since MkDocs uses it as a canonical link and it needs to stay pointing to stable forever.

I've instead introduced a new configuration variable in the plugin called docs_version, which is used in preference of site_url if it is present.

I've updated the docs.

Changes

• Updated configuration in config.py to add docs_version
• Updated plugin.py to add if/else switch to select versioned URL if it's present
• Updated README docs
• Extended test code

Please let me know what you think @pawamoy!

I'm not a Python developer so I hope this is OK for you.

We publish the Vizro docs but we aren't able to version each llms.txt to our needs. This solves our problem, and probably that for other RTD publications that care about having a llms.txt available for every version of their docs. We will still only have the stable version at the root, but plan to link each version of the docs to the appropriate version of llms.txt that's built and stored in the root of that version.

For example, at present, see our llms.txt for an older version of Vizro (0.1.45) that is no longer the stable version: https://vizro.readthedocs.io/en/0.1.45/llms.txt. It's unfortunately pointing to stable versions of the pages. My change here should fix that.

LMK if you need further information or for me to edit this PR description!

[pawamoy]

Thanks, that makes sense. I'd just rename docs_version to something like base_url (and update the docs), because ultimately it's just about changing the base URL, and docs versioning is just one use-case of it. WDYT?

[stichbury]

Oh, great, thanks @pawamoy I am glad it made sense (for a technical writer, I was struggling to explain what I was trying to achieve with this). Certainly, I'll make those changes tomorrow and submit them. Thanks again!

[stichbury]

OK, that's all done. Please let me know if you need anything else from me, and thank you again.

[pawamoy]

Thanks, looking good! Just some nits that I'll batch-apply.