-
-
Notifications
You must be signed in to change notification settings - Fork 143
ENH: Add support for reST-style docstrings #274
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
collerek
commented
Jan 4, 2021
Hi @kernc any update on merging this PR? ;)
Something is still not resolved?
makseq
commented
Nov 3, 2021
kenahoo
commented
Dec 20, 2021
I'd love for :params: support to be merged, anything we can do to help test @kernc ?
scottzach1
commented
Oct 6, 2022
Hi @kernc, I would love to see this functionality within pdoc3.
Is there anyway I can help progress this? 😊
Wingmore
commented
Feb 16, 2024
Any update on this?
kenahoo
commented
Feb 16, 2024
The pdoc code appears to have not been touched in several years. It might be time to either fork it or find an alternative.
456869b to
94d26e8
Compare
31bff05 to
0bcb40f
Compare
Uh oh!
There was an error while loading. Please reload this page.
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