docstrings styles

[igordertigor]

Does (and how) pdoc support different established docstring styles (e.g. google style, numpy style, javadoc, reST)? Are there other "best practice" docstring conventions for formatting docstrings using markdown?

[BurntSushi]

This is all that happens: https://github.com/BurntSushi/pdoc/blob/master/pdoc/templates/html.mako#L62-L72

In my opinion, best practice is to simply describe the contract of the function you're documenting or the invariants of the data you're documenting. The latter can be somewhat tricky to do in Python, but it is one reason why pdoc goes to extra lengths to include documentation on instance variables, for example: https://github.com/BurntSushi/nfldb/blob/master/nfldb/types.py#L475-L479

I tend to also document the types of parameters when it makes sense too, typically by incorporating the type into the description of the contract.

pdoc doesn't otherwise have any rigid guidelines. For example, there's no markup to specifically describe the type of each parameter in a function like what reST supports.

[igordertigor]

Thank you.

[peterjc]

See also #111 for supporting other markup languages like RST, epytext, ... as well as markdown.