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 [Add support for Google Style #101]
• reStructuredText [ __docformat__ reStructuredText/rst etc input as well as Markdown #111]
• Markdown variants [Markdown tables not rendered as tables #64]
• Handling of doctests [Doctests are interpreted by the HTML template #63]
• Epytext [Parsing Epytext #35]
• UML diagrams [UML Diagrams #22]
• ASCII Doc [AsciiDoc support #108]
• Pre-formatted docstrings [use pre tag for docstring #114]
• Formulas [Formulas in pdoc #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?

[H4dr1en]

What is the current status on docstrings? As of 0.7.4, None (Google, numpy, reST) are supported by pdoc, which is very frustrating.

[peterjc]

If you want to add a command line option, using ----docformat as suggested above would match the convention from epydoc (where the files themselves did not contain __docformat__), see:

http://epydoc.sourceforge.net/manual-usage.html

For large inhomogeneous projects being able to set the docstring format on a file by file level is especially useful (converting a lot of documentation at once would be hard to coordinate). But being pragmatic, in my experience a global setting would work fine for most projects.

[mhils]

Hey folks! Better late than never, I'm happy to announce that the latest pdoc release now supports Google-style and numpydoc docstrings. 😃

We're using the --docformat and __docformat__ convention mentioned above.

[ostrokach]

This still does not seem to work in my case, both using pdoc 3.0.0 installed from PyPI and the master branch?

For example, the following code snippet:

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/
    """
    return param1 + param2

gives the following output:

I am invoking pdoc using the following command:

pdoc --docformat google -o docs example/

[ostrokach]

Oh, but it does work if I put __docformat__ = "google" at the top of the file! So I guess I will start a separate issue.

Thanks!

[mhils]

@ostrokach: looks like I butchered this last minute, thanks for the heads-up. Expect a fixed release in a few minutes.

[mhils]

3.0.1 is out, thanks again! 😃

[ostrokach]

Can confirm that it works, thank you!