Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for a docstring format that Sphinx understands #25

Open
AWhetter opened this issue Feb 7, 2022 · 0 comments
Open

Add support for a docstring format that Sphinx understands #25

AWhetter opened this issue Feb 7, 2022 · 0 comments

Comments

@AWhetter
Copy link

AWhetter commented Feb 7, 2022

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant