changeset

Customised versions of Sphinx’s versionadded, versionchanged and deprecated directives to correctly handle bullet lists.

New in version 2.11.0.

Enable sphinx_toolbox.changeset by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.changeset',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

.. versionadded:: version

Documents the version of the project which added the described feature.

The first argument must be given and is the version in question; you can add a second argument consisting of a brief explanation of the change. Alternatively, a longer description my be given in the body of the directive.

.. versionchanged:: version

Similar to versionadded, but describes when and what changed in the feature in some way (new parameters, changed side effects, etc.).

.. deprecated:: version

Similar to versionchanged, but describes when the feature was deprecated. An explanation can also be given, for example to inform the reader what should be used instead.

This extension also adds the following directive:

.. versionremoved:: version [details]

Similar to versionchanged, but describes when the feature was or will be removed. An explanation can also be given, for example to inform the reader what should be used instead.

API Reference

class VersionChange(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: VersionChange

Directive to describe a addition/change/deprecation/removal in a specific version.

setup(app)[source]

Setup sphinx_toolbox.changeset.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata

Examples

.. versionadded:: 2.4
.. versionadded:: 2.5  The *spam* parameter.

.. versionadded:: 2.6
    The *parrot* parameter.

New in version 2.4.

New in version 2.5: The spam parameter.

New in version 2.6: The parrot parameter.

.. deprecated:: 3.1
    Use :func:`spam` instead.

.. deprecated:: 3.2  Use :func:`lobster` instead.

Deprecated since version 3.1: Use spam() instead.

Deprecated since version 3.2: Use lobster() instead.

.. versionremoved:: 1.2.3  Use :func:`foo` instead.

.. versionremoved:: 1.2.3

    Due to an unfixable bug this function has been removed.
    If you desperately need this functionality please write to the mailing list at
    :email:`python-users@example.org`

Removed in version 1.2.3: Use foo() instead.

Removed in version 1.2.3: Due to an unfixable bug this function has been removed. If you desperately need this functionality please write to the mailing list at

.. versionchanged:: 0.3.0

    * Parameters for ``__init__`` can be documented either in the class docstring
      or alongside the attribute.
      The class docstring has priority.
    * Added support for `autodocsumm <https://github.com/Chilipp/autodocsumm>`_.

Changed in version 0.3.0:
  • Parameters for __init__ can be documented either in the class docstring or alongside the attribute. The class docstring has priority.

  • Added support for autodocsumm.