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 (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.
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)
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'
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.
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!
npm install ./node_modules/.bin/webpack
Increment the version in versionwarning/__init__.py
Increment the version in package.json
Update the CHANGELOG.rst
$ npm update
$ npm install $ ./node_modules/.bin/webpack
Commit the changes: git commit -m "Release $NEW_VERSION"
Tag the release in git: git tag $NEW_VERSION
Push the tag to GitHub: git push --tags origin
Upload the package to PyPI:
$ rm -rf dist/ $ python setup.py sdist bdist_wheel $ twine upload dist/*
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|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|
Hashes for sphinx_version_warning-1.1.2-py3-none-any.whl
Hashes for sphinx-version-warning-1.1.2.tar.gz