Skip to content
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

ENH: Add support for reST-style docstrings #274

Open
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

devdrian
Copy link

@devdrian devdrian commented Oct 18, 2020

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

Copy link
Member

@kernc kernc left a 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. 🤔

pdoc/html_helpers.py Show resolved Hide resolved
pdoc/html_helpers.py Outdated Show resolved Hide resolved
pdoc/html_helpers.py Outdated Show resolved Hide resolved
pdoc/test/example_pkg/__init__.py Outdated Show resolved Hide resolved
pdoc/test/example_pkg/__init__.py Show resolved Hide resolved
pdoc/html_helpers.py Outdated Show resolved Hide resolved
Change "restructuredtext" to "epytext" in test_docformat() since
restructuredtext is now (somewhat) supported
Add trailing spaces to reST tags at docstring type inference
@devdrian
Copy link
Author

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.

muecelee added 5 commits October 21, 2020 21:01
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
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
Copy link

collerek commented Jan 4, 2021

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

@Ljancek
Copy link

Ljancek commented Sep 16, 2021

Any update? @kernc @collerek

@makseq
Copy link

makseq commented Nov 3, 2021

@kernc @collerek Why don't you merge it? 🙁

@kenahoo
Copy link

kenahoo commented Dec 20, 2021

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

@scottzach1
Copy link

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

Is there anyway I can help progress this? 😊

@Wingmore
Copy link

Any update on this?

@kenahoo
Copy link

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.

@kernc kernc force-pushed the master branch 3 times, most recently from 456869b to 94d26e8 Compare June 25, 2024 20:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

Support Sphinx / reStructuredText / reST args format No support for classic Sphinx Style docstring format?
8 participants