You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
The text was updated successfully, but these errors were encountered:
Currently a function's or method's arguments are output with the following format:
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:
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.
The text was updated successfully, but these errors were encountered: