{ "info": { "author": "Manuel Kaufmann", "author_email": "humitos@gmail.com", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3" ], "description": "================================\nSphinx Version Warning Extension\n================================\n\n\nSphinx Version Warning is a Sphinx_ extension that allows you to show a *Warning* banner at the top of your documentation.\nThe banner is shown based on the version that is displayed compared (using SemVer_) with the latest version on the server.\n\nThis extension was originally created to be compatible with `Read the Docs`_ API and currently it's the only backend that supports\n(inspired by https://github.com/rtfd/readthedocs.org/issues/3481#issuecomment-378000845)\n\n.. _Sphinx: http://www.sphinx-doc.org/\n.. _SemVer: https://semver.org/\n.. _Read the Docs: http://readthedocs.org/\n\n\nHow it works?\n-------------\n\nWhen visiting a page in Read the Docs that was built with this extension enabled,\nan AJAX request is done to the Read the Docs servers to retrieve all the **active versions** of the project.\nThese versions are compared against the one that we are reading and if it's an old version,\na *Warning* banner appears at the top of the page.\n\n\nExamples\n--------\n\n.. image:: warning-example.png\n\nThere is a live example living at Read the Docs:\n\n- `latest`_ version doesn't show any kind of warning banner\n- `0.0.1`_ version shows a custom message for this particular version\n- `0.0.2`_ version shows a warning banner saying that 0.0.4 is available (at the time of writing this docs)\n- `0.0.4`_ version doesn't show any banner since it's the latest version (at the time of writing this docs)\n\n\n.. _latest: https://sphinx-version-warning-example.readthedocs.io/en/latest/\n.. _0.0.1: https://sphinx-version-warning-example.readthedocs.io/en/0.0.1/\n.. _0.0.2: https://sphinx-version-warning-example.readthedocs.io/en/0.0.2/\n.. _0.0.4: https://sphinx-version-warning-example.readthedocs.io/en/0.0.4/\n\n\nInstallation\n------------\n\nJust run this ``pip`` command inside your virtualenv::\n\n pip install sphinx-version-warning\n\n\nThen in your ``conf.py`` you have to add ``versionwarning.extension`` in the ``extensions`` list.\nShould be similar to::\n\n extensions = [\n 'versionwarning.extension',\n ]\n\n\nRemember to configure the ``versionwarning_project_version`` and ``versionwarning_project_slug`` of your Sphinx project since it's the key for this to work properly::\n\n versionwarning_project_version = '0.0.1'\n versionwarning_project_slug = 'sphinx-version-warning'\n\n.. warning::\n\n If you are building your documentation under Read the Docs,\n ``READTHEDOCS_VERSION`` and ``READTHEDOCS_PROECT`` environment variables will be defined and there is no need to define these variables,\n unless you want to override the default values.\n\n\nCustomization\n-------------\n\nSome customization can be done using the ``conf.py`` file of your Sphinx project:\n\nversionwarning_admonition_type (string)\n type of admonition for the banner (warning, admonition or note)\n\nversionwarning_default_message (string)\n default message for the warning banner\n\nversionwarning_messages (dict)\n mapping between versions and messages for its banners\n\nversionwarning_message_placeholder (string)\n text to be replaced by the version number link from the message\n\nversionwarning_project_slug (string)\n slug of the project under Read the Docs (default to ``READTHEDOCS_PROJECT`` environment variable)\n\nversionwarning_project_version (string)\n slug of the version for the current documentation (default to ``READTHEDOCS_VERSION`` environment variable)\n\nversionwarning_api_url (string)\n API URL to retrieve all versions for this project\n\nversionwarning_banner_html (string)\n HTML code used for the banner shown\n\nversionwarning_banner_id_div (string)\n HTML element ID used for the