3

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.

Michael Reneer
  • 2,271
  • 1
  • 16
  • 22
  • https://stackoverflow.com/questions/7690220/how-to-document-python-function-parameter-types, check this url. – Lavanya Pant Nov 01 '18 at 17:09
  • @LavanyaPant, thanks. The question you linked discusses how to annotate the type of the parameter, which I'm not really interested in. I'm more curious about a standard way to reference the label of the parameter. – Michael Reneer Nov 01 '18 at 17:15

1 Answers1

1

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
Martijn Pieters
  • 1,048,767
  • 296
  • 4,058
  • 3,343
  • Cool, that makes a lot of sense. Now I'm trying to remember why I thought Pydoc supported markdown, weird. – Michael Reneer Nov 01 '18 at 17:20
  • You might have been thinking of `pydoc-markdown`. To be charitable, it is miserable piece of software that does not deliver what the name suggests. – Chris Warth Sep 24 '21 at 16:56