1

I'm using Sphinx to document a python 3 class, and some of the methods in the class have parameter values that are no longer used. What's the best way of marking these as deprecated parameters? There is online documentation referring to marking entire methods as deprecated, but nothing I have found for methods that continue to be active but whose parameters have changed. It may help in my case that these parameters are marked as keyword only.

Added: I'm declaring the parameters like this:

Some function description

:param bool param_a: If True, do something.
:param bool param_b: Deprecated since 0.2.4 - how should I mark this?
:return: An integer.
:rtype: int
user2667066
  • 1,867
  • 2
  • 19
  • 30

2 Answers2

2

The deprecated directive posted Steve Piercy works for me in sphinx v4:

:param str myparam:
    Description of my param

    .. deprecated:: 1.1
        Use mynewparam instead

It's not particularly clear from the info field lists documentation that descriptions of parameters can be multi-line, but they can be.

drootang
  • 2,351
  • 1
  • 20
  • 30
0

Use the deprecated directive.

.. deprecated:: 3.1
    Use ``arg`` instead.
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • 1
    The example there seems to imply that it might be used for the entire function or method. Is there a way (or example) to document the deprecated parameter but also mark it as deprecated? – user2667066 Sep 15 '20 at 13:14
  • It depends on whether you document your args. If you do, then put the directive where you document them. – Steve Piercy Sep 15 '20 at 14:25
  • I have added to the question to show how I'm documenting params. I'm not sure how to squeeze the `.. deprecated::` directive in there? – user2667066 Sep 15 '20 at 14:44
  • 1
    That will not work because only text is supported in that context, no parsing. I meant more like this https://docs.pylonsproject.org/projects/pyramid/en/latest/api/authentication.html#module-pyramid.authentication and its source docstring https://docs.pylonsproject.org/projects/pyramid/en/latest/_modules/pyramid/authentication.html#AuthTktAuthenticationPolicy (scroll to end). – Steve Piercy Sep 16 '20 at 01:35
  • Ah yes, I can describe the parameter as deprecated in the free text description of the method, and flag up that paragraph as something to do with deprecation. But I can't seem to explicitly mark the parameter description text as deprecated in any consistent way. – user2667066 Sep 16 '20 at 12:20
  • 1
    What have you tried? Please edit your answer. I don't think that the parameter description in a [field list](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists) can be parsed as reStructuredText if it contains block syntax, but you can try, making sure you use proper indentation. It might be able to parse inline syntax, such as `:term:`. – Steve Piercy Sep 16 '20 at 19:08