sphinx-version-warning

================================ Sphinx Version Warning Extension

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)

.. _Sphinx: http://www.sphinx-doc.org/ .. _SemVer: https://semver.org/ .. _Read the Docs: http://readthedocs.org/

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

.. image:: 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)

.. _latest: https://sphinx-version-warning-example.readthedocs.io/en/latest/ .. _0.0.1: https://sphinx-version-warning-example.readthedocs.io/en/0.0.1/ .. _0.0.2: https://sphinx-version-warning-example.readthedocs.io/en/0.0.2/ .. _0.0.4: https://sphinx-version-warning-example.readthedocs.io/en/0.0.4/

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

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

#. Increment the version in versionwarning/__init__.py #. Increment the version in package.json #. Update the CHANGELOG.rst #. Update npm::

 $ npm update

#. Compile assets::

 $ 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/*