pdoc icon indicating copy to clipboard operation
pdoc copied to clipboard

reStrucutured text :param: :return: support

Open SmirnGreg opened this issue 5 years ago • 1 comments

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

SmirnGreg avatar May 13 '20 08:05 SmirnGreg

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 :scream:)~~,
  • [ ] accounting for other Sphinx keywords (param, type, raises, return, rtype),
  • [ ] added a unit test.

kernc avatar May 13 '20 12:05 kernc