Welcome to sphinx-version-warning!¶
sphinx-version-warning
is a Sphinx extension that allows you to show a Warning banner at the top of your documentation.
By default, the banner is shown based on the version that is displayed compared (using SemVer) with the latest version on the server.
- Online documentation:
- https://sphinx-version-warning.readthedocs.io/
- Source code repository (and issue tracker):
- https://github.com/humitos/sphinx-version-warning/
- Badges:
Why do I need this extension?¶
You probably don’t.
Read the Docs implements this feature by itself adding a banner for you in old versions.
Although, comparing this extension with Read the Docs’ core functionality,
sphinx-version-warning
allows the user to highly customize the banner by changing the message,
the style, the position, etc. which is not possible with Read the Docs feature.
The default settings behaves in the same manner that Read the Docs’ core functionality, so you will want to check out Configuration for a better customization.
Note
This extension was inspired by this comment on the Read the Docs issue tracker, where some discussions about what was missing from Read the Docs’ feature took place.
How does it work?¶
When visiting a page in Read the Docs that was built with this extension enabled, an AJAX request is done to the Read the Docs Public API to retrieve all the active versions of the project. These versions are compared against the one that the user is reading and if it’s an old version, a warning banner appears at the top of the page.