sphinx-version-warning 0.0.1

Sphinx extension to add a warning banner

Sphinx Version Warning is a Sphinx extension that allows you to show a Warning banner at the top of your documentation. The banner is shown based on the version that is displayed compared (using SemVer) with the latest version on the server.

This extension was originally created to be compatible with Read the Docs API and currently it’s the only backend that supports.

How it works?

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 servers to retrieve all the versions of the project. These versions are compared against the one that we are reading and if it’s an old version, a red Warning banner appears at the top of the page.

Examples

There is a live example living at Read the Docs:

• latest version doesn’t show any kind of warning banner

• 0.0.1 version shows a custom and fixed message added at build time

• 0.0.2 version shows a warning banner saying that 0.0.3 is available (at the time of writing this docs)

• 0.0.3 version doesn’t show any banner since it’s the latest version (at the time of writing this docs)

Installation

Just run this pip command insider your virtualenv:

pip install sphinx-version-warning

Then in your conf.py you have to add versionwarning in the extensions list. Should be similar to:

extensions = [
    'versionwarning',
]

Enable it and setup the Read the Docs project’s slug:

versionwarning_enabled = True
versionwarning_project_slug = 'sphinx-version-warning'

Remember to configure the version of your Sphinx project since it’s the key for this to work properly:

version = '0.0.1'

Customization

Some customization can be done using the conf.py file of your Sphinx project:

versionwarning_enabled (bool)

enable/disable version warning extension

versionwarning_default_admonition_type (string)

type of admonition for the banner (warning, admonition or note)

versionwarning_default_message (string)

default message for the warning banner

versionwarning_message (dict)

mapping between versions and messages for its banners

versionwarning_message_placeholder (string)

text to be replaced by the version number link from the message

versionwarning_project_slug (string)

slug of the project under Read the Docs