By default, ReadTheDocs (RTD) shows the 'latest' version of a package's Sphinx-generated documentation that tracks the master branch. This can be confusing to users, who most likely will have the most recent release of the package installed. Thus, they may see something in the documentation that is specific to unreleased features, and does not match up with the version of the package they have installed. A similar problem is with people seeing the documentation for an old release (most likely through a link on Google).
There are two builtin-settings on RTD that help with this, and that should be enable for any package that has had a "stable" release:
-
Show the "stable" version by default: in the RTD "Admin" tab, select "Advanced Settings" and switch "Default version" from "latest" to "stable"
-
Show warnings for old version: In the same "Advanced Settings", check the "Show version warning" box
This still leaves the problem of the unstable 'latest' version of the documentation. We can solve the problem by adding some custom javascript to the Sphinx documentation:
-
Put the
version-alert.jsfile into thedocs/_staticsubfolder of your project (credit: django-anymail) -
Load the javascript by adding the following in
docs/conf.py:def setup(app): # ... app.add_javascript("version-alert.js")
See the documentation of the krotov package for an example of how this looks:
An alternative approach would be to insert the warning statically via a plugin, but the javascript method works much better, most importantly because it is able to include a link to the current "stable" version of the same page. There is also a "sphinx-version-warning" plugin, but as far as I can tell, this was just a prototype to the builtin "Show version warning" option on RTD; I was not able to use it to show a warning on 'latest'.