Agreeing on a Python3 "doc string" format

[portante]

Can we agree on adopting the "Google" doc string formats that can be used to generate Sphinx documentation?

See the blog post, 3 Different Docstring Formats for Python.

[dbutenhof]

I believe we've more or less standardized on the google format, which I find a lot more readable than either of the others presented here. My main criticism is be that with type hints, redundantly including the type again in the "Args" line is excessively redundant. 😏

Assuming Sphinx is smart enough to understand type hints, presumably we can omit that bit of ugly?

[webbnh]

My concern is that the Google format (which is probably the best of those three) is a little heavy for anything but "interface" functions. That is, for "helper" functions and similar subroutines, we should really strive to make the code self-documenting (i.e., the function name should describe its purpose, the parameter names should describe their values, and the type hints will fill in most of the rest). If what we want to be able to do is to produce externally-facing documentation from the source code, then that's fine, but we don't need that level of documentation for everything, so I would like to have the freedom to pick and choose when we need a full-blown docstring a la Google and Sphinx. In general, I would like to reserve the docstring for saying things that developers need to know in order to read or use the function; I really don't want the docstring to just reiterate stuff which is already in the function signature.

I don't want our documentation requirements to get in the way of making the code accessible to the developers and reviewers.

[portante]

Where did we arrive at the conclusion that adopting "Google" doc string formats are for every function? We have not published our APIs on the python side for the agent or server, but when we do, we are going to want to generate documentation for them. Agreeing as a team to use the "Google" format for such documentation would be a help.

We need to correct wherever it is that suggests it would have to be adopted for everything.

[webbnh]

I'm not opposed to having a docstring for (nearly) every function; I just want the docstring to add value, and it needs to add enough value to justify the space that it takes up. For interface functions, the generated documentation provides significant value, so it's worth dedicating the space to it (and, the full-blown docstring serves as a reminder that it is attached to a function with external visibility), and it's OK if it repeats information which is already in the function signature, because the consumer of the generated documentation probably won't see the signature.

What I want to avoid is bloat in the code which is not supporting external documentation...how does Sphinx know which is which?

[ndokos]

How to document subset of functions - maybe?

[webbnh]

Fascinating: so Sphinx is a Python app which loads our code and uses introspection to pull out all the docstrings? And, because of that, we can write filters, functions, and other bits of processing? Hmmm...gosh...the possibilities seem endless....

[riya-17]

+1 for Google Docstring

[dbutenhof]

I can easily imagine two kinds of documentation: a formal API documentation for clients, which applies mostly at this point to the Agent and specifically Tool Meister environments; and an internal developer API documentation which ideally would expose all of our internal APIs in searchable form.

For server clients, we want API documentation, not Python method/class documentation; I don't doubt that Sphinx has support for generating these (I know that Django does), but it's not from standard Google method docstrings.