improvement: Implement support for NumPy-style docstrings #279
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR implements support for NumPy-style docstrings via the new
NumpyProcessor
class. It does so with the help of the numpydoc package, on which this PR makes Pydoc-Markdown dependent.In addition to the above, this PR:
NumpyProcessor
SmartProcessor
to supportNumpyProcessor
pyproject.toml
to reflect the addition of numpydoc as a dependencyreadme.md
to reflect the addition of NumPy-style docstring supportThis PR resolves #251.
Caveats and Limitations
NumpyProcessor.check_docstring_format()
returnsTrue
if a docstring passes numpydoc's docstring validator without warnings or errors andFalse
otherwise. BecauseSmartProcessor
skips the call tocheck_docstring_format
if the format is explicitly indicated in the docstring (e.g., with@doc:fmt:numpy
), a docstring that would fail numpydoc's validator but nonetheless explicitly identifies itself as a NumPy-style docstring may result in warnings or exceptions at processing time.NumpyDocString
objects before converting them to Markdown syntax. Instantiating aNumpyDocString
object with an invalid docstring will result in warnings or exceptions.NumpyProcessor
can be found below.Examples
Here are examples of how the various sections of a NumPy-Style docstring are rendered by
NumpyProcessor
.Summary / Extended Summary
The Summary and Extended Summary are rendered together as a single summary.
Input
Output
Decode a string by shifting each character by a given offset.
There's not much else to say about this function, but if there was, it would go here. Fun fact: you don't need to include the Extended Summary heading — if your summary spans multiple lines, everything after the first will be implicitly considered to be the Extended Summary. You can't have both an implicit and explicit Extended Summary, though — that causes an exception!
Parameters / Other Parameters / Attributes / Recieves
The Parameters, Other Parameters, Attributes, and Receives sections are all rendered similarly.
Input
Output
Arguments
str
): The string to decode.int
): The offset by which to shift each character in the string. Defaults to 13.Attributes
Any
): Functions don't have attributes, but if we were documenting a class, we'd put its attributes here. Unfortunately, we are not. Too bad!Receives
Any
): If this was a generator, we'd document the parameters passed to it'ssend()
method here. Unfortunately, it is not. Too bad!Returns / Yields
The Returns and Yields sections are rendered similarly.
Input
Output
Returns
str
: The decoded string.Yields
str
): The decoded string, one character at a time. By the way, you can optionally annotate your return and yield values with names like I did here. The type annotation isn't optional, though.Raises / Warns
The Raises and Warns sections are rendered similarly.
Input
Output
Raises
ValueError
: If the string contains non-alphabetic characters.Warns
UserWarning
: If I don't like you.See Also
Input
Output
See Also
(The processor leaves the task of cross-referencing functions, classes, and methods in this section to Pydoc-Markdown's existing faculties.)
Notes
Input
Output
Notes
This function implements an inverse substitution cipher1.
References
Input
Output
References
Examples
The Examples section supports doctests. The processor renders doctests in code blocks and other content as plain text.
The processor considers the start of a doctest to be marked by a line beginning with
>>>
and the end of a doctest to be marked by a blank line. If multiple doctests are present, they are rendered in separate code blocks.Input
Output
Examples
This is a super simple function so I don't really know why you'd need more than one example but here's another one anyway.