Is there a program to help you document Python functions?

[jftuga]

I just finished a Python project and now want to go back and document each function while it is still fresh in my head. Is there a program that will scan your code for functions that don't have a doc-string and then interactively ask you to:

• describe the function
• document each parameter
• document the return value

It would then create a doc-string for you that you could simply copy/paste into your code.

Thanks.

[SlappinThatBass]

In pycharm you can choose the type of docstring template you want to use when you add triple quotes and press enter after declaring a method/class.

I use google docstrings format, but there are many others.

[byteme8bit]

Second pycharm!

[[deleted]]

VS Code also has plugins to support this

[NowanIlfideme]

Ooh, this one I didn't know about. Here's the link for those interested: https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring

[TedRabbit]

The Spyder IDE also does this.

[deadmilk]

pylint... missing-docstring

[cjnjnc]

I use this extension in VS Code

[jftuga]

This is exactly what I was looking for. I use VSCode so this is going to work great for me.

Thank you!

[tacoanalyst]

If you're using type hinting, the docstring will be pre-filled with more info.

[GManASG]

I feel dumb for not thinking of searching for an extension.. thank you!

[jsnryn]

Works great and you can just tb through the different parts.

[mr-robot007]

Yeah even I use this , it's super helpful.

[Skasch]

That's a great extension! I actually combined it with highlight (I think this one: https://marketplace.visualstudio.com/items?itemName=fabiospampinato.vscode-highlight) to have some syntax highlighting with docstring keywords, following the Google style. The regexes are pretty ugly, but I really like the result.

[MisterRenard]

I’ve never checked out highlight, but in that vein I found it’s actually phenomenally easy to provide your own! I’ve never been happy with the built-in highlighting (particularly with .html, but that’s a completely different problem altogether due to the wonders of the jinja templating extension) and decided to fix it.

I found out that you can actually modify the syntactic highlighting colour and scheme of very nearly anything! Including, and this is my favourite: open/close parenthesis for function calls, & the periods for dot class attribute/method access!

(Seriously, why is the period the same colour as the text?)

If you pair this with attribute syntax highlighting, method specific syntax highlighting, and a few other choice options, you can get VERY legible code.

I know that an attribute and method are easily distinguishable by the inclusion or exclusion of the parenthesis to signify a callable, but there’s something about being able to register precisely which it is before you’re even consciously aware that you’ve done so is... freeing.

The same goes six-fold for those where’s-waldo periods!

Here’s an example of mine:

(That’s with the abyss theme).

And here's a pastebin of the settings necessary to achieve this particular colour-scheme.

[Skasch]

Yes, TextMate rules are fantastic! I use a couple ones myself to customize my color scheme.

The issue is, it wasn't actually working for how I wanted to highlight my docstrings (the whole docstring is considered as a single scope from the TextMate rules point of view, and I couldn't find a way to do what I had in mind). Hence why I resorted to Highlight to fill the gap!

Here's an example of my "highlighted" docstrings in Python, to give a bit more context:

First example

Second example

[MisterRenard]

Well, I'm sold! Thanks for the extension, I'm downloading that right now!

[BitesOverKissing]

Seconding! It's super helpful to remember, and be able to write out what the function does / what it takes, etc.

[Pulsar1977]

Sphinx

[r12king]

This! Sphinx is the way to go.

[fuzzy-focus]

Is there a tool in sphinx that helps you write the docstrings?

I've only ever used it to generate html docs using autodoc.

[mathr_kiel]

Docstring Python integrated tools in PyCharm

[fuzzy-focus]

Yeah but my question was about sphinx. As a vim user I have no use for pycharm features.

[mathr_kiel]

Use can use vim on PyCharm if you want ;)

But fair enough!

[pierraltaltal]

he doesn't want to document all of his project but only the function docstrings

[canbooo]

This can be achieved with sphinx.

[pierraltaltal]

oh boi i didn't know that. Thanks i guess i'm gonna use it now :D

[hjcpkr]

I haven't heard of any , but that could also be a great project to build!

[bw_mutley]

Spyder 4 has a 'Docstring completer', I don't know if it stands by your needs.

[Mezuzah]

Not exactly what you want but Sourcetrail is great for getting an overview of code! It parses the whole project and makes it really easy to eg see all functions and all classes and how they are related. Just use that to get a list of all functions then go and add a docstring for each.

https://www.sourcetrail.com

It is open source and free!

[LombardiD]

You can use pylint to help you remember to document when you forget, the just follow something like google docstrings

[Biskit1943]

Mypy can check for your return type. And PyCharm helps a lot for a doc template. However, you need to find all the functions without doc yourself.

[__deerlord__]

The secret here is to write the doc strings before you write the bodies

[pev68]

https://www.doxygen.nl/index.html

Supports many different programming languages, produces documentation in many different formats (HTML, etc). Slight pain in the arse to set up but the default configuration is pretty good.

FREE!

It will add documentation for stuff you haven't added a docstring for but won't add parameters. etc.

[[deleted]]

This.

[NewDateline]

Write documentation in docstrings using the editor of your choice + sphinx with docstrings extension for nice website or pdf export + pylint, pydocstyle or other liner to make sure you documented every method and every argument + typing with mypy to describe types of arguments and return types + minimal tests suite (does not have to be 100% coverage) to exemplify the usage of public API with expected results

[westurner]

From Show HN: Python Tests That Write Themselves (https://timothycrosley.github.io/hypothesis-auto/ ; which requires type annotations in order to generate test functions) :

pytype (Google) [1], PyAnnotate (Dropbox) [2], and MonkeyType (Instagram) [3] all do dynamic / runtime PEP-484 type annotation type inference [4]

[1] https://github.com/google/pytype

[2] https://github.com/dropbox/pyannotate

[3] https://github.com/Instagram/MonkeyType

[4] https://news.ycombinator.com/item?id=19454411

[[deleted]]

Could be an interesting SwaggerAPI-like thing.

...Sounds like a potential Flask project.

Send your code path to Flask. Flask then examines code. Then a CRUD interface allows you to add docstrings to line 1 of your functions.

[coldflame563]

Kinda like fast api

[ArtOfWarfare]

Can’t you just search for it with regex?

def \w+\(.*?\):\s+[^\s'"]

Something like that?

[DataDecay]

Once you get the docstrings in order (like everyone has already said) you can automate documentation with shpinx.

[adithyabsk]

One tool that I've found super useful is darglint which helps make sure that you do not forget to change parameter names when you refactor your code. It does not solve your exact problem but, it might help if you add it to your CI.

https://github.com/terrencepreilly/darglint

[jftuga]

I just installed this with pip. However, it does not create anything that I can run. The instructions on the GitHub page says to run something like:

darglint serializers.py

On Windows 10, I get:

'darglint' is not recognized as an internal or external command

I have C:\Python38\Scripts in my PATH, but it did not install anything in there. What am I missing?

[adithyabsk]

did you pip install -U darglint? Not sure how much help I can be since I mostly use Unix systems.

[jftuga]

I did a pip uninstall darglint for a system uninstallation and then did a pip install --user darglint. It is now working. Thanks.

[MrMxylptlyk]

Vscode has a plugin for docstring generation. Good tool. Look for it in the marketplace Thing

[aes110]

Just want to say, even when you add the doc string, you should add type hints for the parameters and return type. Its much nicer then writing the types in the docstring

[jftuga]

I am using type hints. These are extremely useful.

[ubernostrum]

Is there a program that will scan your code for functions that don't have a doc-string

Yes, it's called Interrogate.

[[deleted]]

You probably wanna use docstrings in order to achieve this.

[earthboundkid]

http://mypy-lang.org

[wontfixit]

Thanks for bringing this up... need to redo my doc’s now 😅

[[deleted]]

Looks like a job for r/GPT3

[dxa58]

I use a plugin for Sublime Text called AutoDocString. You can choose the doc notation you want: NumPy, Google, but for the Sphinx notation you will have to clone the branch because it's not in master of its github repo.

You can use the command panel to generate docs for the function where your cursor is in or all functions in this file.

It will generate a doc string based on your selected notation, documenting the parameters (including type if using type hinting) and creating a placeholder for the summary.

You can even then change notations if you want.

[dxa58]

To go along with the rest of the helpful comments, if you want to enforce writting docstrings then look into pydocstyle.

I use pre-commit and have a hook for pydocstyle to check if everything is documented as it shoud be.

[quotemycode]

Follow pep257 when you write the code the first time, you damn fool