How to document Python function parameters with sphinx-apidoc?

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
   """

Solution 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.

Solution 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.

Comments

[Adam Morris]

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:

[ddotsenko]

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

[ddotsenko]

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

[Rotareti]

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