search

spadarian / docblock-python

Atom plugin to insert documentation blocks for python functions
GNU General Public License v2.0
22 stars 9 forks source link

Support Sphinx docstyle #25

Closed guillochon closed 5 years ago

guillochon commented 5 years ago

As described here: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists

Kilo59 commented 5 years ago

You may already be aware but Sphinx can support Numpy or Google Style Docstrings with the Napoleon extension. https://github.com/sphinx-contrib/napoleon

I believe you can pip install it, add the extension to your conf.py and it will just work without extra configuration.

guillochon commented 5 years ago

I am aware, unfortunately my company insists upon this particular docstring format.

Kilo59 commented 5 years ago

My condolences 😉

I know this isn't what you wanted, but you might give pyment a try. It's a python based command line tool you can use to generate docstrings in different formats. https://github.com/dadadel/pyment/blob/master/doc/sphinx/source/pyment.rst

If you are willing to ditch Atom, there is also the autoDocstring VScode plugin.

Both of these tools support the Sphinx/reST style.

guillochon commented 5 years ago

pyment looks like a nice option, thanks!

And yes I saw that VScode has a plugin to do the format I want (and so does pycharm), but I'm resisting the urge to switch over...

spadarian commented 5 years ago

I will add the new style, so need to change to VScode.

spadarian commented 5 years ago

@guillochon I don't use that specific style, so let me know if I need to fix or add something.

guillochon commented 5 years ago

@spadarian I have one requested thing to add: A checkbox option to separate param description and type, like so:

:param variable This variable describes this.
:type  variable string

This is immensely helpful already though!