How to document Python function parameters with Sphinx?

Question

I'm trying to clean up my python code documentation, and decided to use sphinx-doc because it looks good. I like how I can reference other classes and methods with tags like:

:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function

I'm trying to figure out though how to document parameter names in a function, so that if I have a function like:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something?:`parameter1` And then describe the parameter.

   """

What's the best practice for this?

Update:

The correct syntax is:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something parameter1: And then describe the variable
   """

Daylong

Check out the Napolean extension for Sphinx, which allows doc strings in either Google or Numpy style, both of which look nicer that plain Sphinx. – Kassandrakassaraba

Also of interest: pydev.org/manual_adv_type_hints.html – Petrarch

Answer 1

Typically "function variables" are called parameters ;).

It's documented here: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures

And the answer is :param ________

EDIT Disclaimer: I've never used or heard of sphinx... This post is mostly a "what words to search for." Hope it helped.

Languishing

Thanks... I was searching for the wrong thing. I had tried param at some point, but kept getting errors, and didn't realize the syntax was not :param:variable1, but :param variable1: – Daylong

sphinx-doc.org/domains.html#id1 and pythonhosted.org/an_example_pypi_project/… – Touching

Conventions for documenting complex parameters (lists, dicts etc) - jetbrains.com/pycharm/webhelp/type-hinting-in-pycharm.html – Touching

@Crisfole, I think the link in your answer doesn't point to the right page. – Carven

Answer 2

Adding this answer to consolidate options:

pydoc is basic with no special formatting

epydoc uses the format '@param var:'

Doxygen is oriented for a larger range of languages

Sphinx uses the format ':param type var:'. Also see more examples. This was used to create the Python 3.5 documentation.

Majka

Answer 3

How to document types

It is also worth noting the old syntax :type parameter2: MyClass for parameter type, also documented at https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures

But with Python 3 typing we can just:

main.py

class MyClass:
    """
    This class does that.
    """
    def __init__(self, i):
        self.i = i

def do_this(parameter1: int, parameter2: MyClass):
   """
   This function does this.

   :param parameter1: my favorite int
   :param parameter2: my favorite class
   """
   return parameter1 + parameter2.i

build.sh

sphinx-build . out

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = [ 'sphinx.ext.autodoc' ]
autodoc_default_options = {
    'members': True,
}

index.rst

.. automodule:: main

requirements.txt

Sphinx==6.1.3

Output on out/index.html:

Note how it correctly links the parameter type to the documentation of the class MyClass.

Make types appear next to the description instead

Can be done by adding the following to your conf.py:

autodoc_typehints = "description"

See also: How to make Sphinx show Python 3 typing type hints next to the argument description instead of on the function signature?

:type: example

For reference, the pre-typing approach looked like:

def do_this(parameter1, parameter2):
   """
   This function does this.

   :param parameter1: my favorite int
   :type parameter1: int
   :param parameter2: my favorite class
   :type parameter2: MyClass
   """
   return parameter1 + parameter2.i

which produces output identical to the autodoc_typehints = "description" version with typing, but with more duplication as we have to type (no pun) parameter1 and parameter2 yet again.

Other useful typing related things to know

• how to represent multiple types: How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?
• how to link to the documentation of types of external projects: Specifying targets for intersphinx links to numpy, scipy, and matplotlib

Tested on Ubuntu 22.10, Python 3.10.7.

Celestyna

To get more readable function signature documentations, check also autodoc_typehints = "description" Sphinx option sphinx-doc.org/en/master/usage/extensions/autodoc.html – Cattalo

@MikkoOhtamaa blasphemy! Types next to signature are the True path. – Celestyna

The default option is unreadable if your function has any complex types as arguments or more than three arguments. – Cattalo