sphinx-doc.el icon indicating copy to clipboard operation
sphinx-doc.el copied to clipboard

Published 20 hours ago • verified publisher icon naiquevin

Switch to `pydocstring` backend ?

Open wizmer opened this issue 3 years ago • 6 comments

Hi !

I have discovered the existence of https://github.com/robodair/pydocstring. Instead of re-invented the wheel, I think it could be worth replacing the current sphinx-doc backend by the pydocstring one. What do you think @naiquevin ? I can make a proof of concept draft PR if necessary.

wizmer avatar Dec 15 '21 10:12 wizmer

Hi @naiquevin , happy new year ! What do you think of my proposal ? I think using a real python backend to generate the docstring can be much more powerful than using the the elisp code we currently have. It can also handle more cases and also more styles (it currently supports google, numpy, reST).

wizmer avatar Jan 06 '22 10:01 wizmer

Hi @wizmer Happy new year to you too. I missed your earlier message, sorry about that. I don't mind the change you are proposing. But IMO, it'd be good if the current implementation of generating docstring in elisp is also supported as a fallback in case pydocstring is not installed in the environment. What do you think?

naiquevin avatar Jan 07 '22 05:01 naiquevin

Have you guys considered pyment? seems more active project than pydocstring and IIUIC does the same thing isn't it?

zzantares avatar Jan 13 '22 05:01 zzantares

@naiquevin Yes, I think keeping a fallback option would be nice.

@zzantares Thanks for your suggestion, I was not aware of pyment, it seems indeed more active and also more complete. I'll give it a try.

wizmer avatar Jan 14 '22 08:01 wizmer

On the emacs side of things there's also https://github.com/glyph/python-docstring-mode, unfortunately unmaintained currently. Bringing it up because it's tangentially related. It also uses its own implementation. Perhaps there's room to build something that does both?

timlod avatar Jan 18 '22 10:01 timlod

I have started refactoring pyment here https://github.com/dadadel/pyment/pull/112 I also plan to enhance it and make it more customizable.

That will be for the backend side but when I'll be done with it, it will be time to think whether to integrate it in sphinx-doc or build a new package if it goes too much beyond sphinx-doc scope. Also, sphinx-doc name suggests that it is only for sphinx docstring while pyment is able to handle more styles.

wizmer avatar Jan 18 '22 12:01 wizmer