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.

回答1:

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.