CODEWITHSUNDEEP
pythonpython-sphinxdocstring
Dwayne
Dwayne

Reputation: 925

Referencing parameters in a Python docstring

I use Sphinx and the autodocs feature to ensure we have good docs in our project.

So I'm familiar with info field lists and I'm familiar with using cross-referencing in our docs.

However, when writing docstring for a method or function I find it useful to refer to their parameters in the text. But there doesn't seem to be a structured way to do this.

  1. We could say e.g.

    Use ``name`` to set the username

    but that has no structure, requires you to remember what style you used for that and if you change style you have to hunt down and kill all the incorrect styles.

  2. :param: doesn't work outside of a info field list so you can't write

    Use :param:`name` to set the username

  3. I've seen some projects use :parm: but that isn't documented and doesn't seem to work. So they must have some customisation

  4. I could use generic_roles but that seems like me working around a problem that I'm sure others have encountered.

So hopefully I've just missed something blindingly obvious.

Upvotes: 16

Views: 2329

Answers (1)

sions
sions

Reputation: 107

You can write your own extension using autodoc-process-docstring - it's really simple.

Have the extension search for :param: and replace it with your choice of style.

Upvotes: 1

Related Questions