Napoleon: more custom docstring section styles

[SolidifiedRay]

Although the napoleon_custom_sections option help renders custom docstring section, the style is inconsistent with the rest of the doc.

For example, I have a custom docstring section Side Effect. I would like it to be displayed as returns or parameters docstring section. However, napoleon_custom_sections option rendesr Side Effect in a different style shown in the following picture.

It will be really helpful if we can customize the custom sections a bit more. The following setting has a similar effect, but it renders the Parameters name instead of the custom name.

napoleon_use_param = False
napoleon_custom_sections = [('Custom name', 'Parameters')]

I would like to do something like the following so that my Custom section has the same style as the Parameter section, and it still keeps my custom name:

napoleon_custom_sections = [("Side Effects", "display_like_parameters"), ...]

or

napoleon_custom_sections = [("Side Effects", "Parameters") ]
napoleon_custom_section_rename = False # True is default for backwards compatibility.

The following link includes more details about the solutions:
Format custom "Side Effects" docstring section in-toto/in-toto#401

Others people have expressed a similar desire (see sphinx-contrib/napoleon#2)

If you are interested, I would like to provide a PR for this. Thanks!

[tshead]

Boy, I could really use this right away. If it were up to me:

• napoleon_custom_sections would be called napoleon_custom_aliases, and only accept a list of (new alias, existing section) tuples.
• A hypothetical new napoleon_custom_sections would only accept a list of (new section, existing section) or (new section, callback function) tuples, and the output would always use new section as the title, in either case.

That would be a backwards-incompatible change, but you could argue that the current behavior isn’t actually documented in the Sphinx docs, and thus is fair game.

Cheers,
Tim

[tk0miya]

I also don't know napoleon module has such option. It was added at #4387. It has not been documented, but it was introduced in CHANGES. So I consider it's a secret feature. So -1 for incompatible change.

But I'm interested in the enhancement itself. Could you submit a PR please? I'll take a look.

[SolidifiedRay]

Sorry for the late reply. I just submit a PR #8658. You might want to have a look when you find some times. @tk0miya
Thank you and happy new year!