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'

Warning

If you are building your documentation under Read the Docs, READTHEDOCS_VERSION and READTHEDOCS_PROECT environment variables will be defined and there is no need to define these variables, unless you want to override the default values.

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.

Files for sphinx-version-warning, version 1.1.2
Filename, size File type Python version Upload date Hashes
Filename, size sphinx_version_warning-1.1.2-py3-none-any.whl (13.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size sphinx-version-warning-1.1.2.tar.gz (12.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page