Custom docstring section

[somnambWl]

Is it possible to add a custom docstring section? I sometimes need to add a section with different name which is not listed in allowed section headers. When I run sphinx, the section header is deleted from the result.

[rmax]

I'm also looking into this. We have a class that uses environment variables and we are not sure what section to use to document that.

[asmeurer]

The code has a mechanism for custom sections. I'm not sure how to use it as it doesn't seem to be documented.

But why not just have a flag to allow arbitrary section headers, instead of just the pre-allowed ones? Based on my reading of the code, this should be trivial to implement.

[ianling]

I found this in the docs for Napoleon: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html#sphinxcontrib.napoleon.Config.napoleon_custom_sections

But I can't seem to get it working. In my function's docstring, I have:

    """
    Queries the server for the full contents of a User's texture or comment, or a Channel's description.

    Args:
        user_textures(iterable): a list of Users to retrieve textures for (Default value = ())
        user_comments(iterable): a list of Users to retrieve comments for (Default value = ())
        channel_descriptions(iterable): a list of Channels to retrieve descriptions for (Default value = ())

    Events:
        USER_COMMENT_UPDATED
        USER_TEXTURE_UPDATED
        CHANNEL_UPDATED
    """

In conf.py, I added napoleon_custom_sections = ['events']. I've also tried capitalizing 'Events'.

My rendered doc page ends up looking like this: https://i.imgur.com/kmLj1wG.png

[ianling]

I figured out that ReadTheDocs was using an old version of Sphinx from before Napoleon supported this option. I added a requirements.txt file to the base of my repo with one entry in it: sphinx>=1.8.2.

Now the napoleon_custom_sections option works, but it looks inconsistent with the rest of the docs. https://i.imgur.com/Il8s6Dq.png

This is my docstring right now:

    """
    Queries the server for the full contents of a User's texture or comment, or a Channel's description.

    Args:
        user_textures(iterable): a list of Users to retrieve textures for (Default value = ())
        user_comments(iterable): a list of Users to retrieve comments for (Default value = ())
        channel_descriptions(iterable): a list of Channels to retrieve descriptions for (Default value = ())

    Events:
        - USER_COMMENT_UPDATED
        - USER_TEXTURE_UPDATED
        - CHANNEL_UPDATED
    """

Is there a way to make it look more consistent with the Parameters section?

[1313e]

Is there a way to make it look more consistent with the Parameters section?

Yes, you can, by adding ('Events', 'Parameters') to napoleon_custom_sections instead of just 'Events'. This will use the correct lay-out, but it will also use the section title 'Parameters' instead of 'Events'.

And this is exactly why I was coming over here, since I was having some problems with this. Is there a possibility that an alias can be created, like @ianling tries to do, such that the same formatting is used, but that it still uses the same section title? So, basically, the two different custom section options combined (the generic section which keeps the section title and the aliased section which uses a different formatting).

[xiumingzhang]

Exactly as @1313e said. Is there an update on this? Having the title being a custom one and meanwhile the format being the aliased section's would be really nice.

[zlatko-minev]

Ditto

[SolidifiedRay]

I have a similar desire and face the same problem that @1313e pointed out:

Now the napoleon_custom_sections option works, but it looks inconsistent with the rest of the docs. https://i.imgur.com/Il8s6Dq.png

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

[SolidifiedRay]

Hi @RobRuana. I am willing to provide a PR that creates a configurable custom docstring section. Will you be interested in it? If so, do you prefer any of the proposed solutions that I comment on above? Thanks!

[lukpueh]

FYI: https://github.com/sphinx-doc/sphinx/pull/8658 adds the feature discussed here to the Napoleon extension that comes with sphinx, and has been merged. Kudos to @SolidifiedRay for providing the patch!

[1313e]

When exactly would that be available in Sphinx, if you know the answer of course?

[lukpueh]

When exactly would that be available in Sphinx, if you know the answer of course?

Unfortunately I don't, but looking at the release cadence I suppose fairly soon? (cc @tk0miya, the maintainer who merged the feature).

[tk0miya]

The release cycle of Sphinx is every other month. So it will be released in Feb (maybe mid of Feb).

[BenSouchet]

@SolidifiedRay big thanks for the work you have done to add this feature (thanks also to @tk0miya and @lukpueh).

I looked to see if It was possible to add custom section similar to the Parameters one but with a custom name and now it's possible !

For people on the internet who are looking for the same thing, to add a custom section named "Data Inputs" which behaves like the parameters section, add this in your conf.py :

napoleon_custom_sections = [('Data Inputs', 'params_style')]

Now you can add something like this in your docstrings :

    Data Inputs:
        param1 (int): Info on the first data parameter.
        param2 (str): Details on the second data parameter.

In case this didn't work for you this is the versions of my packages:

Sphinx==3.5.4
sphinxcontrib-apidoc==0.3.0
sphinxcontrib-napoleon==0.7

[adam-grant-hendry]

I would like to see this functionality extended to class-level docstrings (see #33), particularly enabling developers to document class variables (e.g. pyqt signals and slots) in addition to __init__ methods. Currently, the Google Style Docstrings Example state not to mix-and-match docstrings at the class level and in the __init__ method, as both apply to the __init__ method, but mixing is necessary (at a minimum) when classes have both class variables and __init__ methods.

[adam-grant-hendry]

For additional reference, please see this SO question. Simply using an Attributes header does not distinguish between instance vs. class attributes/variables, so I would like to be able to change the header to Class Variables or Class Attributes.