Add --docformat argument for reStructuredText or plaintext input

[peterjc]

This leaves markdown as the default for rendering the docstrings, but adds a new --docformat option (named after the epydoc option) allowing the use of reStructuredText (via docutils) or plain text (using an HTML <pre> block).

This will be useful for anyone hoping to migrate from epydoc which did not support Markdown, but did support its own format epydoc and the Python standard reStructuredText.

This will also indirectly greatly improve the display of doctests or Python snippets using the >>> notation which the Markdown rendering does not understand (see #63).

It would be relatively simple to make the markdown/docutils import lazy, so that people using one input format would not require the other dependency be installed.

This would close the main goal of #111 (although it does not make life complicated by looking at the per-file settings in any __docformat__ declaration).

Thank you to @j6k4m8 whose work on #101 was very useful. I would be happy to include his work by adding GitHub Flavoured Markdown as another option here, e.g. --docformat gfm?

[j6k4m8]

Awesome!!

I really like this idea. Feel free to PR this on my fork too if you'd like; would love to merge this in right away and get to use it!

[peterjc]

I think it might need some merge conflicts resolved, but I have no objection to you doing this @j6k4m8

[skjerns]

Is there any update on the RST support?

[peterjc]

Sadly I have not seen any feedback from @BurntSushi on this or related ideas.

(In the meantime, I have spent time with sphinx-apidoc, trying to get that to give me usable API documentation. That work is also stalled on an open pull request. Note I found pdoc much simpler to use.)

[skjerns]

Thank's I'll have a look into sphinx-apidoc.
If you have any hint on how to easily create html-docs from reST docstrings, let me know. sphinx can do it, but the documentation is terrible.

[cortesi]

Hi there! We've decided not to support RST in pdoc. I realise this might be a painful choice, but we feel pdoc will be better if it remains small and focused, with a single markup format.

[karolzmijewski]

Is it finally supported or not? I'm a bit confused, because regarding doc we can choose restructuredtext as a docformat:
docformat: Literal['markdown', 'google', 'numpy', 'restructuredtext'] = 'restructuredtext',
but when I try to use it, It doesn't parse the docstring as I expect

[peterjc]

@karolzmijewski this pull request was not merged, see discussion on #153 instead.

Also see https://github.com/mitmproxy/pdoc/blob/main/CHANGELOG.md#2021-01-24-pdoc-300 - minimal RST support was added in 2021-01-24 pdoc 3.0.0:

• Add support for alternative docstring flavors. Flavors can be enabled globally using --docformat or on a per-module basis using __docformat__ = "...".
• Add support for Google docstrings.
• Add basic support for Numpydoc and reStructuredText docstrings. The most common rST elements are supported, but we do not intend to support the full complexity of the spec.