[FeatureRequest] Support the numpy docstring format

[dhirschfeld]

The numpy docstring format is very popular in the scientific python community.

The numpy docstring format is supported by the numpydoc and napoleon sphinx extensions.

[pawamoy]

With the numpy format, it feels like we're getting closer to rst again 😕

But I (now) see the value of supporting multiple formats.

As said in this comment, we could implement multiple format parsers for docstrings.

I think we can also get inspiration (or re-use the code) from sphinx.ext.napoleon.

Maybe the code responsible for parsing the docstrings should also be split into another Python package. I think other projects could benefit from such a library.

Design propositions and pull requests are welcome as I don't have much time these days to tackle this 🙂

[StephenBrown2]

With the numpy format, it feels like we're getting closer to rst again 😕

Personally I think that if one wants numpy formatting, they should use a different extension. Each one should focus on its own strengths.

[thebigmunch]

Maybe the code responsible for parsing the docstrings should also be split into another Python package. I think other projects could benefit from such a library.

Like this one? I haven't tried it out yet as I only searched for it after reading this issue but might be worth looking into.

[pawamoy]

Yes! Ideally this package would be extended to support the other requested formats as well as the one currently in use in mkdocstrings.

[pawamoy]

Moving this issue over pytkdocs which is now responsible for docstring parsing!

[pawamoy]

Pull requests are welcome. All the code related to the parsing of docstrings is in https://github.com/pawamoy/pytkdocs/blob/master/src/pytkdocs/parsers/docstrings.py. Feel free to try and add support for other docstrings format! If you have any questions, ask on Gitter: https://gitter.im/pytkdocs/community

[pawamoy]

There's a base parser now (#28). This should ease (slightly) the process of implementing another parser. Just copy paste the google parser into a new numpy.py module, and adapt the code 🙂! The only method that must be implemented in the parser subclass is parse_sections. You'll have access to the following attributes and methods:

• self.error(message): record an error. message is a string. The object path will be inserted at the beginning of the message, so you don't have to prefix it yourself.
• self.object_path: the object's path.
• self.object_signature: the object's signature (inspect.Signature) or None
• self.object_type: the object's type or None