Wish: Custom sections

[nritsche]

I would like to be able to define custom sections so they don't create warnings when I use them.

This would be very helpful in our project: https://github.com/chime-experiment/dias

for example here

[jnothman]

Would you want to configure how these were treated/displayed?

[nritsche]

Just displaying them somehow would be a good start, I think.

[fkiraly]

Any update on this?

I think numpydoc is great, but it also has a serious drawback when documenting class/object methods or impure functions (with side effects), since there seems to be no clean way to document assumptions on the context and effects on it.

As a very common example, suppose a class/object method that assumes presence of an attribute self.a and writes to an attribute self.b. This needs to be documented by doc standards 101, but there's no clear place where it goes. Notes? That's for explaining content, algorithm, math. Parameters? self.a is not really a parameter. Description? That should be high-level, not detail documentation regarding context, state, side effects. And so on...

[j9ac9k]

Just going to add that this is a wish list item for pyqtgraph.

In addition to fields like Parameters, we want to add another section, Signals (see example of Qt signals).

Presently this can be done with the napoleon extension with the following bit in conf.py:

napoleon_custom_sections = [("Signals", "params_style")]

Here is the bit in the docs about the functionality:

https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_custom_sections

[stefanv]

That sounds like a reasonable feature to add.