Add NumPy Docstring Style Support

[EthanC]

Just as discussed in #47 with the Google Docstring format, it would be great to have support for NumPy Docstrings; An example of which can be found here.

[TejasAvinashShetty]

Maybe one could make use of mktheapidocs plugin from Mkdocs plugins list

[tcbegley]

@TejasAvinashShetty have you managed to get that working? I tried it, but don't think I configured things quite correctly.

[TejasAvinashShetty]

Nope, I have not tried it yet. I just suggested it as a quick fix. Hopefully, when I get time I will try it out.

[lsorber]

• Are there any plans to support NumPy-style docstrings?
• If not, what is the recommended documentation format to use with portray? In my opinion, Markdown is by itself is not a documentation format but a document markup language.

[rtbs-dev]

@timothycrosley @kylebarron @sanzoghenzo This is possible to solve once this is merged. However, portray is using it's own text.mako, it appears, so installing the PR doesn't directly solve this issue.

Is it possible to make portray rely on the pdocs mako template by default? Otherwise the files will need to be updated in both places to maintain feature parity.

[sanzoghenzo]

I see that portray's template adds a class_level variable to the function function that determines the level of the heading ("h3" if class_level is false, "h5" otherwise); pdocs has it fixed at "h4".

@timothycrosley is this an intended feature, or can this be merged in pdocs and proceed as @tbsexton asked?

[rtbs-dev]

Following up to link the work @sanzoghenzo and @kylebarron did on pdocs that adds the mentioned class_level and enables other docstring formats.

I suppose the last step is relying on pdocs' own text.mako, or at least duplicating the functionality from there. I believe mako has the ability to inherit/extend templates?

[sanzoghenzo]

I didn't test it, but I think all that is needed is to remove the text.mako file and this line, so that portray doesn't force the default template and pdocs uses its own.

[JannikKlauke]

@sanzoghenzo I monkey patched it locally and it seems to work by deleting that line and the default text.mako. At least for very simple documentations mixing several docstring styles produced no errors and looked clean to me.