display banner link to stable docs from latest and old docs

[davidism]

RTD will display a banner when viewing old versions of docs that links to the highest released version. We'd like to display a banner when viewing the latest docs as well, so that users don't try to use features that aren't released yet. For examples, see Flask or Django.

[RichardLitt]

This sounds good to me.

[stsewd]

This seems that was implemented a long time ago (#587 (comment)), I don't know what happened with that feature.

[davidism]

That's going from old to stable, I'm asking for latest to stable.

[lb-]

We are running into this same issue with our Wagtail docs wagtail/wagtail#3375

Some people end up viewing the latest and are not sure that it is actually the development version (ie. not stable).

[humitos]

I'm taking a look at the discussion here and I think there are different cases here that should be considered:

1. inform the reader he is reading an "unreleased" version when seeing latest

   • this is not useful for all the projects, since there are project that uses latest as their main documentation and probably they won't want to see this note at all
   • not all the projects will want the same message for this

     • for example Flask shows

       Warning: This is the documentation for the development version of Flask

     • and Django shows

       This document is for Django's development version, which can be significantly different from previous releases. For older releases, use the version selector floating in the bottom right corner of this page.

2. accessing an old stable tag (like 1.10 when 1.11 already exists)

   • some projects will want to inform this to the readers and some other projects, like Django with long term support version, won't want this
     • accessing to 1.11 in Django doesn't show any kind of message: https://docs.djangoproject.com/en/1.11/, but accessing 1.9 shows a message (see below)
     • accessing any of the non-stable Flask versions (0.10, 0.11, 0.12) don't show any message

3. accessing a old stable tag (like 1.9 when 1.11 already exists) shows a customized message

   • when accesing Django 1.9 documentation (https://docs.djangoproject.com/en/1.9/) it doesn't say that it's old but it says that this version is unsecure:

     This document is for an insecure version of Django that is no longer supported. Please upgrade to a newer release!

Implementation design?

So, I think we need to do several things here to handle all of these cases:

• whether or not a general message should be shown when accessing an old version. For example,

  You are not seeing the latest stable version of this docs. is the latest stable.

  • how does the user include the link to the version he want to refer? Includes something like {{ latest_stable_version }} (and/or {{ latest_version }}, any other choices?) in the message?

• each Version should have the ability to set wheter or not a message should be shown and what message (overrides the general rule if defined). With this, we cover the cases that some old specific versions shown a different message but also the "unreleased" case for the latest Version

  • the only tricky case here is the one that the user doesn't want to show any message for the latest version but he does want to show a general message for old versions. So, we need to override it here, but put an empty message? (kind of a hack?)

Where all these configs should live?

Since this is general to the project itself (*), I think they can't go in the YAML file (at least before we define a general rule for this at readthedocs/readthedocs-build#46) and should be modified using the Admin interface and save some things in the Project model and some others in the Version model (I don't really like this, but I don't see a better option ATM)

(*) there are specific messages for specific versions, but if you create a tag 2.1 and in the future you want to update the message shown, you won't "update the tag to add a message" :)

How/Where the user set these configs?

I'm imagining something under https://readthedocs.org/dashboard//versions/ where all the versions are listed and you can mark a checkbox which will show a text box to introduce the general message for old stable versions plus a checkbox per version that will show a text box for the custom message for that specific version.

How are these messages shown in the docs?

This should work similarly as it's working right know using the AJAX request to footer_html endpoint to get the version latest version, but instead of retrieving numbers the endpoint should return the whole HTML rendered for the note since there could be custom messages.

So, probably it worth to create a different endpoint for this instead of using the footer one.

Q: "This logic only applies for tags and won't work for branches", is this a true statement? What happen with mixed Version of tags and branches?

---

I think this covers all the cases. It sounds that not trivial work is needed to implement it and probably more UX decision are needed also to make it more user friendly.

Although I think I didn't miss any use case that we have seen in the past days, I would appreciate that you comment here if your use case is not covered here or there is a mistake in my understanding of any of them.

Please, @rtfd/core, can you share your thoughts here?

[ericholscher]

This is way too overcomplicated. I'd argue that we should remove this feature, before we try to build such complexity into it. I've already tried in the past to automate "is this version supported?" and it proved impossible to do in a generic way.

In particular, setting this per-version seems like way too much overhead, and likely not something that is specifically useful for users. In particular, the version's state will change over time, so it adds a large burden to maintainers.

The question we need to answer here is "what value are we providing?" -- I think we mainly need to:

• Warn people that they are on an deactivated version

I think the "warn people about a new version" is also prone to a lot of failure cases, as we've seen, so probably that functionality should be removed. People can maintain warnings themselves at the Sphinx level, as I don't think this is a platform feature that we can scale to all projects in a meaningful way.

[davidism]

Given that the RTD context is documented now, and contains the version information necessary to implement this, that would be fine. It just means you need a custom theme if you want to show it.

[humitos]

I agree with @ericholscher, but this complexity is the only thing that I found that allows us to manage all these cases (which I consider valid and not crazy --given the examples of Flask and Django)

It just means you need a custom theme if you want to show it.

I'm not very into how to create a custom theme regarding:

• how much time it could take?
• how complicated could be to just override a section?
• how much programming knowledge you need?
• etc.

After reading this phrase, maybe what we need is to document "How to make a small derivated custom theme to add these types of notes as you need".

So, we end up with the generic rule (already implemented and useful to many people) but if it doesn't fit your needs, you can read this article and make it work for your specific case.

How complicated it could be to write this kind of guide? and, how complicated it could be to follow this guide for a user that doesn't have ton of experience with programming?

[davidism]

Extending the RTD theme / template locally isn't particularly complicated, but it's not thoroughly documented on Sphinx's side. I'd recommend not making people do this just to get a dev / old version message. It seems like something that should already be part of the RTD theme since RTD is already doing a lot with the version information.

[ericholscher]

It's not a custom theme, it's a simple Sphinx extension that could implement the logic and render it on the pages. The hard part is defining what versions are active/supported/newest. We've had a number of bugs in our tries to do this automatically, so it seems like something that must be manual.

I think we could build an opt-in system that let users define which of their versions are supported, but then we still have to define which is the "highest" for the redirect, which again runs into the version comparison problem.

I just don't see a way that RTD can provide value here, without having users explicitly define exactly what do to (eg. soft redirect this version to that version) -- and at that point, it would be much better to do in a generic Sphinx extension that can integrate with RTD data, instead of a bunch of additional logic in our codebase to maintain.

[davidism]

I implemented this in our own theme, so as long as we can get information for all the versions during build (#3482) or add extra context globally (#3483) then we don't need RTD to do anything here.

[humitos]

I implemented this in our own theme

@davidism Can you pointed me to this? I'm interesting on building a sphinx extension at some point. Started a PoC for this at https://github.com/humitos/sphinx-version-warning

[davidism]

This code parses and adds to the context: https://github.com/pallets/pallets-sphinx-themes/blob/master/pallets_sphinx_themes/versions.py, which is read in this template for the sidebar: https://github.com/pallets/pallets-sphinx-themes/blob/master/pallets_sphinx_themes/pocoo/versions.html, and this one for the banner: https://github.com/pallets/pallets-sphinx-themes/blob/master/pallets_sphinx_themes/pocoo/layout.html

It requires passing version information as extra context when building each version. You can see it in action on the Flask docs: http://flask.pocoo.org/docs/dev/quickstart/

There are various things in our docs (not all of it has been extracted to the themes repo) that I may extract into extensions later.

[humitos]

Just in case that someone else arrives at this issue, I just published a very small sphinx extension that allows project's owner to get a similar behaviour than the one described in this comment: #3481 (comment)

There are still work to do to make it more customizable but it's a good starting point: https://github.com/humitos/sphinx-version-warning