Docstring flavors

[cortesi]

I'm opening this ticket to unify discussion of docstring flavors. We have a wide range of requests for these, including:

• Google style [#101]
• reStructuredText [#111]
• Markdown variants [#64]
• Handling of doctests [#63]
• Epytext [#35]
• UML diagrams [#22]
• ASCII Doc [#108]
• Pre-formatted docstrings [#114]
• Formulas [#87]

I'm going to close all these tickets so that we can explore which direction to take in one place. When I first took on pdoc, I thought we could get away with supporting one and only one format. Having read carefully through all of the related tickets, I've now softened that a bit, and I think that there's an argument for being pragmatic.

My feeling is that we should clearly cater for doctests and pre-formatted docstrings, and choose a more flexible markdown renderer that includes Github-style tables and the like. Equally, I feel we should clearly not include support for reStructuredText, which is way too large and complicated. I'm undecided about things like Google style and EpyText, which are intermediate.

It's possible that we could use a Github-style type marker for this:

"""raw
   
    This is a pre-formatted docstring.
                 Indentation will be preserved.
"""

And:

"""google
A Google-style docstring.

Arguments:
     argname (type): Description.
     secondarg (type : default): Description.

Returns:
    boolean: True on success.
"""

The downside of this is that it introduces a weirdness to docstrings that make them less nice for both humans in code editors and other documentation tools. Another possibility (fronted in some PRs) is to control this unilaterally for an entire module with a command-line flag. This has the issue that the format is not specified in the code (where I feel it should be), and that many modules will be heterogenous and require support for multiple formats. Thoughts?

[peterjc]

In epydoc you could set this in the code at file level with __docformat__, see rejected PEP258 and other documentation:

https://www.python.org/dev/peps/pep-0258/#choice-of-docstring-format

Reusing this convention seems far preferable to inventing another.

[kernc]

Could we have __docformat__ rather a key in __pdoc__? The pep was rejected and the idea of namespaces predates it anyway.

As oposed to __docformat__ being a string, needing of us to implement/wrap all sorts of formatters, it could also be a Callable[[str], str]?

[armant]

Controlling with a command-line flag seems sensible and pragmatic to me. If I rebase and resubmit #101, will it be considered?

[armant]

Bumping this

[mhils]

From what I've read so far I think there'd be no strong objections to just start with a universal command-line flag (for example, --docformat).
If we then find that to be insufficient and would like to add support for heterogenous modules, we can add support for __docformat__, which would override the command line flag.

Thoughts?