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:
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>`_.
Parameters for
__init__
can be documented either in the class docstring or alongside the attribute. The class docstring has priority.Added support for autodocsumm.