Skip to content

Add support for a docstring format that Sphinx understands #25

Open
@AWhetter

Description

@AWhetter

Currently a function's or method's arguments are output with the following format:

Parameter ``arg1``:
    This is the description.
    This is a continued line of the description.

Parameter ``arg2``:
    This is the description.

Throws:
    Exception1 This is when the exception is thrown.

Throws:
    Exception2 This is when the exception is thrown.

Sphinx then renders this as (depending on the theme)

Parameter arg1:
    This is the description.
    This is a continued line of the description.

Parameter arg2:
    This is the description.

Throws:
    Exception1 This is when the exception is thrown.

Throws:
    Exception2 This is when the exception is thrown.

The docstring format that Sphinx understands that this closest to is the Google Style docstring (https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#google-vs-numpy). This would look like the following:

Parameters:
    arg1: This is the description.
        This is a continued line of the description.
    arg2: This is the description.

Raises:
    Exception1: This is when the exception is thrown.
    Exception2: This is when the exception is thrown.

Which would render as (depending on the theme)

Parameters:

  • arg1 -- This is the description. This is a continued line of the description.
  • arg2 -- This is the description.

Raises:

  • Exception1 -- This is when the exception is thrown.
  • Exception2 -- This is when the exception is thrown.

Please could pybind11_mkdoc output docstrings in a format that Sphinx understands so that they render like any other Python docstring would.

The quickest way to implement this would to aim to have pybind11_mkdoc output Google style docstrings. Given how close the current output format is to the Google docstring style, this boils down to supporting grouped sections (eg Parameters and Raises).

However we could chose to output as rst and still get the desired output with Sphinx. Obviously this would be much more work. For the most flexibility, the user could choose the output format that they desire. Personally I don't need this extra flexibility because I use Google style anyway.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions