ENH: Add support for reST-style docstrings

[devdrian]

Hi kernc and all contributors,

Addressing issues #110 and #273, I added support for reST-style docstrings, following your suggestions in #198.

Additionally, in case the docformat is not explicitly specified, it will be distinguished between reST-style and Numpy-/Google-style in html_helpers.to_markdown.

Fixes #110 Fixes #273 Closes #198

[devdrian]

Thanks @kernc for your review and your suggestions!

I changed it now to utilize docutils. It's not the cleanest solution right now: Everything but the tag lists - for which Markdown is still generated - is converted directly to html using docutils' publish functions. But it definitely opens up the possibility in the future to integrate some more advanced features.

For reST I also disabled the admonitions preprocessing, since docutils processes them directly. However, some of the directives from the reST_directives test are not supported and generate a warning message. I chose to leave the messages - which are placed in a div at the corresponding position - in for now, since it allows the user to fix this. But we can discuss if that's the best way. For the reST test, I adapted the admonitions to only include ones that are directly supported by docutils.

[collerek]

Hi @kernc any update on merging this PR? ;) Something is still not resolved?

[Ljancek]

Any update? @kernc @collerek

[makseq]

@kernc @collerek Why don't you merge it? :slightly_frowning_face:

[kenahoo]

I'd love for :params: support to be merged, anything we can do to help test @kernc ?

[scottzach1]

Hi @kernc, I would love to see this functionality within pdoc3.

Is there anyway I can help progress this? 😊

[Wingmore]

Any update on this?

[kenahoo]

The pdoc code appears to have not been touched in several years. It might be time to either fork it or find an alternative.