CODEWITHSUNDEEP
pythonpydoc
Michael Reneer
Michael Reneer

Reputation: 2571

Is there a structured way to reference function parameter labels in Python docstring?

I am using the tool pydoc to automatically generate documentation. Given the function:

def sum(a, b):
  """Returns the sum of a and b."""
  return a + b

I am curious if there is a structured way to use markdown to highlight references to function parameter labels? For example:

"""Returns the sum of 'a' and 'b'."""
"""Returns the sum of `a` and `b."""
"""Returns the sum of *a* and *b*."""
"""Returns the sum of **a** and **b**."""

Similar to this question Referencing parameters in a Python docstring which is about using Sphinx instead of pydoc.

Also note, that I am curious about referencing the labels (not the types) of the function parameters.

Upvotes: 3

Views: 1915

Answers (1)

Martijn Pieters
Martijn Pieters

Reputation: 1121634

There is no markdown support in Pydoc.

Formatting in docstrings is limited to recognising PEP and RFC references, self. attribute references and links for existing names (for other classes, methods, and functions) when rendering to HTML, so in in that mode, some names are already going to be marked up. This doesn't extend to argument names however.

Pydoc does use inspect.signature() output as the basis for formatting the function, so if you make sure you have informative type hints, then you'll at least get to document the types of the arguments and return value.

So a (rather contrived) definition using a generic TypeVar definition instead of sticking to float, like:

from typing import TypeVar

Number = TypeVar('Number', int, float)

def sum(a: Number, b: Number) -> Number:
    """Produce the sum of the two numbers, a and b"""
    return a + b

comes out in pydoc as

sum(a: ~Number, b: ~Number) -> ~Number
    Produce the sum of the two numbers, a and b

Upvotes: 1

Related Questions