Menu
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.
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.
:param: doesn't work outside of a info field list so you can't write
Use :param:`name` to set the username
I've seen some projects use :parm: but that isn't documented and doesn't seem to work. So they must have some customisation
So hopefully I've just missed something blindingly obvious.
518
Class method docstrings should contain the following: A brief description of what the method is and what it's used for. Any arguments (both required and optional) that are passed including keyword arguments. Label any arguments that are considered optional or have a default value.
All functions should have a docstring. Accessing Docstrings: The docstrings can be accessed using the __doc__ method of the object or using the help function.
Best practicesAll modules, classes, methods, and functions, including the __init__ constructor in packages should have docstrings. Descriptions are capitalized and have end-of-sentence punctuation. Always use """Triple double quotes.""" around docstrings. Docstrings are not followed by a blank line.
The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated.
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.
86
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
