sphinx-contrib/multiversion

Version banner template example doesn't work because latest_version is hardcoded to 'master'

Opened this issue · 4 comments

jli commented

(First off, thanks for your work! My project was stuck on an old version of Sphinx due to using sphinxcontrib-versioning, and I'm almost done switching us over to sphinx-multiversion 🥳 )

Background

The template example for "version banners" is exactly what I'd like to use: when the user is viewing an unreleased version, warn them that it is in development; and if they are viewing and older released version, warn them that there's a newer version available.

Problem

However, the example doesn't work on my repo (using Sphinx 2.4.4 and sphinx-multiversion 0.2.4). The latest_version HTML context variable was None.

It seems like this context variable is based on the smv_latest_version config value, set to "master" by default. My repo doesn't have a "master" branch, which I guess is why the context variable is None.

Ideally, I'd like to configure sphinx-multiversion to dynamically use the greatest released tag version as the latest version, instead of a static config value.

Mapping to sphinxcontrib-versioning's options:

  • smv_latest_version seems to be the same as scv_banner_main_ref
  • the feature I would like to have is scv_banner_greatest_tag
  • another related feature is scv_banner_recent_tag (for treating the most recently created tag as the latest version)
  • scv_sort defines the sort ordering

Potential improvements

  • Add documentation for the smv_latest_version config value.
  • Add a boolean config like smv_latest_version_is_greatest_tag (or extend the semantics of smv_latest_version to read a certain sentinel value?

If you're supportive of this idea, but feel that it's low priority, I may be able to find some time at work to contribute a patch.

Thanks!

LewisGaul commented

FWIW the example didn't work for me either, and would also be interested in having a version-based page banner :)

cedricbonhomme commented

For your information I think I solved this issue with this:

{% extends "!page.html" %}
{% block body %}
{% if current_version and latest_version and current_version != latest_version and current_version != release and current_version.name != latest_version.release %}
<p>
  <strong>
    {% if current_version.is_released %}
        {% if latest_version.release.replace('v', '').split('.') | map('int') | list > current_version.name.replace('v', '').split('.') | map('int') | list  %}
          You're reading an old version of this documentation.
          If you want up-to-date information, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
        {% endif %}
    {% else %}
    You're reading the documentation for a development version.
    For the latest released version, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
    {% endif %}
  </strong>
</p>
{% endif %}
{{ super() }}
{% endblock %}%

so with this horrible test:

latest_version.release.replace('v', '').split('.') | map('int') | list > current_version.name.replace('v', '').split('.') | map('int') | list

  • 👍1
schmoelder commented

For our own project, I did some digging into the issue.

First, if you look at the documentation of @Holzhaus's own project Mixxx (for which he built sphinx-multiversion in the first place), you can see that you can actually set smv_latest_version in conf.py.

https://github.com/mixxxdj/manual/blob/5165e797563e46accfd2dbb10fe80fc5109c414a/source/conf.py#L106

Instead of hard coding this into the conf file, I thought it would be much more convenient to override this value using the -D option of sphinx-build/sphinx-multiversion. However, then i got the following warning:

unknown config value 'smv_outputdir_format' in override, ignoring

So I did some further digging. The smv config is added to Sphinx here (if add_default = True):
https://github.com/Holzhaus/sphinx-multiversion/blob/cdc9cb591a738e67a5aacc458f9c95e2b88a94c2/sphinx_multiversion/main.py#L41

So I added this to sphinx.py

DEFAULT_LATEST_VERSION = 'master'

and this to main.py

current_config.add(
    "smv_latest_version",
    sphinx.DEFAULT_LATEST_VERSION,
    "html",
    str,
)

However, in main, when we loop over all the git refs, the function is called without the add_default argument (which itself is False by default. So by calling with

current_config = load_sphinx_config(confpath, confoverrides, add_default=True)

I could enable setting the latest version from the cli.

Maybe this also helps someone else.

Oh, I also had to use the alternative regex pattern for 'smv_released_pattern' as described in #66 .

@Holzhaus if you are willing to accept it, I will also create a PR for this.

Edit: I just realised that my approach is flawed as it now always takes the default values and the overridden ones but ignores what is defined in conf.py. I will keep on trying! ^^