docstring format for api, possibly across code base?

Extracted from #3130 (review)

We currently don't have a desired style to write docstrings.

Should we come up with one? If so, which one?

[bhavaniravi]

Most of the standards suggest """ for docstrings. I think we should go with the same.

https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format

[jorgeorpinel]

Thanks @bhavaniravi! I think thus much we can all agree on 🙂

The larger question is what text format to use INSIDE docstrings. Ref: https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format

[Suor]

I don't think we should spend time formalizing this, we have very limited amount of user facing functions really. And we may find better way to spend our time than argue about docstring formatting.

[shcheklein]

@Suor I think you brought this topic, right? :) Are we good to close it (discussion around formatting) then and let Jorge decide this, for example?

[jorgeorpinel]

I agree it's only important at the moment to have good full code doc for the API functions and I'm happy to just pick one format but would prefer to get some feedback from the @iterative/engineering team. In fact I wanted to summarize the options here (extracted from #3130 (comment) +):

is there a standard way of doing markup that is understood by the tools that generate a view for this (like F1 in PyCharm, quick help in VS Code, docs generators, etc) ?

Among doc generators, Sphinx is by far the most popular, with pdoc a remote 2nd place, it seems. Sphinx uses reStructuredText format. pdoc is interesting because it supports Markdown and other nicer-looking formats worth checking out actually (from Numpy and Google).

As for IDEs, VSCode intellisense doesn't interpret any format in the docstrings it seems. It mostly focuses on building and inspecting the Python code by itself. From what I can see here, PyCharm auto completion works similarly.

So easy to read docstrings e.g. numpydoc or Google style may be best if we expect IDEs code completion will be the main way users reach our docstrings. And especially since we're writing the API documentation manually anyway (not generating it).

---

p.s. An interesting VSCode extension to help write docstrings in any of the above formats is https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring, BTW.