镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

reStrucutured text :param: :return: support - #198

Open
SmirnGreg wants to merge 4 commits into
pdoc3:masterfrom
SmirnGreg:master
Open

SmirnGreg wants to merge 4 commits into
pdoc3:masterfrom
SmirnGreg:master

Conversation

@SmirnGreg

@SmirnGreg SmirnGreg commented May 13, 2020 •

Copy link
Copy Markdown

Dear @kernc, maintainers,

For issue #110 I have implemented quite a dirty hack that adds the reSt :param x: and :return: directives replacing them with the Google-style docstring.

This does not break any of the tests, but I have not implemented a specific test for it, while it works in my case.

Fixes #110

@kernc

kernc commented May 13, 2020 •

Copy link
Copy Markdown
Member

Doesn't seem cumbersome a transliteration, given its brevity so far. However, I'd much prefer it with the following points addressed:

  • the whole transliteration a separate procedure in e.g. _ToMarkdown.sphinx_params(),
  • the procedure returning valid, complete markdown, not Google Args: (permitted to call through _ToMarkdown.google() if needed),
  • the implementation based on re.sub() instead of str.replace() (or maybe even docutils 😱),
  • accounting for other Sphinx keywords (param, type, raises, return, rtype),
  • added a unit test.

@kernc kernc left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't blame you if the above seems like too much work. It'd be a nice addition, though.

This branch has not been deployed

No deployments
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

2 participants