Skip to main content

Sphinx extension to add a warning banner

Project description

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 (inspired by https://github.com/rtfd/readthedocs.org/issues/3481#issuecomment-378000845)

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

Examples

warning-example.png

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 message for this particular version

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

  • 0.0.4 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 inside your virtualenv:

pip install sphinx-version-warning

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

extensions = [
    'versionwarning.extension',
]

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

versionwarning_project_version = '0.0.1'
versionwarning_project_slug = 'sphinx-version-warning'

Customization

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

versionwarning_admonition_type (string)

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

versionwarning_default_message (string)

default message for the warning banner

versionwarning_messages (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 (default to READTHEDOCS_PROJECT environment variable)

versionwarning_project_version (string)

slug of the version for the current documentation (default to READTHEDOCS_VERSION environment variable)

versionwarning_api_url (string)

API URL to retrieve all versions for this project

versionwarning_banner_html (string)

HTML code used for the banner shown

versionwarning_banner_id_div (string)

HTML element ID used for the <div> inject as banner

versionwarning_body_selector (string)

jQuery selector to find the body element in the page and prepend the banner

How to contribute?

Pull Requests are always welcome!

Generate assets

npm install
./node_modules/.bin/webpack

Releasing

  1. Increment the version in versionwarning/__init__.py

  2. Increment the version in package.json

  3. Update the CHANGELOG.rst

  4. Update npm:

    $ npm update
  5. Compile assets:

    $ npm install
    $ ./node_modules/.bin/webpack
  6. Commit the changes: git commit -m "Release $NEW_VERSION"

  7. Tag the release in git: git tag $NEW_VERSION

  8. Push the tag to GitHub: git push --tags origin

  9. Upload the package to PyPI:

    $ rm -rf dist/
    $ python setup.py sdist bdist_wheel
    $ twine upload dist/*

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-version-warning-1.1.2.tar.gz (12.2 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page