Adding parameters to module docstrings with Python Sphinx

Question

I have a docstring in the beginning of every module describing its usage and functionality. Here I also want to add the most relevant parameters - like settings in a parameter file or via command line arguments. It's no classical function parameters since the module might be called as stand-alone as well (via if __name__ == '__main__' capture). But since the ordinary parameter formatting of Sphinx is neat I want to just re-use it.

However, Sphinx seems to handle the "Parameter" section differently when in a module compared to when in a function.

This is how they are formatted differently:

Parameters in function docstring:

Parameters in module docstring:

You see the difference. In functions the keyword "Parameters" is added and then we have a nice bullet list. In modules no title is created, no list, the type is not set in braces but on an additional line etc.

Docstring format is the same (numpydoc):

Parameters
----------
pars : dict
    Parameter dictionary.
key : str
    Parameter name.

vs.

Parameters
----------
num_axial_segments : int
    The number of axial rotor segments.
magnet_segmentation_method : int
    The method of magnet segmentation.
    0: Uniform segmentation (all magnets same amount of segments).

Does anyone have an idea why it's handled like this? And what I can do about it?

I would like the parameters in modules output in the same way as in functions.

Answer 1

The style used to render the docstring sections is dependent on the HTML theme you are using with Sphinx.

Does anyone have an idea why it's handled like this?

The reason the styles are different for module and function docstrings, is because it's customary to use a command-line syntax style to document scripts that is different from function signature syntax style . Notice the style you showed for the module docstring is similar to a list of command-line arguments.

I would like the parameters in modules output in the same way as in functions.

Different themes may render module docstrings similarly or differently from function and classe docstrings. You would have to choose a different theme or customize the theme's CSS by copying the style used for functions to the style used for module docstrings.

the type is not set in braces but on an additional line etc.

This is noteworthy because you would expect the napoleon-sphinx extension to not render type and name on different lines as if it were using classic reST syntax instead of Google style or Numpy.

I would recommend trying a different HTML theme or setting the napoleon_use_param , napoleon_use_ivar and napoleon_use_rtype explicitly to see if there's a difference.

And what I can do about it?

The examples given for Google style or Numpy style suggest using docstring sections but that's somewhat oversimplified because command-line style syntax is better illustrated and automated by the way argparse implements it. There are a few extensions meant to ease and automate the process of documenting scripts.

As for the difference in style I wouldn't worry about it (admittedly in the HTML theme you are currently using it doesn't look very good). A command-line invocation of a script or a run-time call of a function are different and accordingly themes may and will render those docstrings sections with visual differences.