ENH: Add support for reST-style docstrings #274
Conversation
There was a problem hiding this comment.
I like it. But now I worry people will expect all sorts of further reST magic to work, such as references (:class:`foo.Foo` ; :obj:, :func:, :module:, ...), anchors and hyperlinks ...
I wonder if we shouldn't instead incorporate docutils, or maybe defer to docutils.publish_string() at least the descriptions. 🤔
Change "restructuredtext" to "epytext" in test_docformat() since restructuredtext is now (somewhat) supported Add trailing spaces to reST tags at docstring type inference
|
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. |
Change "restructuredtext" to "epytext" in test_docformat() since restructuredtext is now (somewhat) supported Add trailing spaces to reST tags at docstring type inference Clean up code wrt linter
…doc into reST_style_docstrings_support
In html_helpers.reST_node_to_html() return an empty string in case the regex can't find a div with class "document" Specifiy variable types where not inferable
|
Hi @kernc any update on merging this PR? ;) |
|
I'd love for |
|
Hi @kernc, I would love to see this functionality within pdoc3. Is there anyway I can help progress this? 😊 |
|
Any update on this? |
|
The |
kernc
force-pushed
the
master
branch
3 times, most recently
from
456869b
to
94d26e8
Compare
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