Docstring format

[taion]

Sounds like we have two contenders here:

• Sphinx format
• Google format

Sphinx is used by:

• CPython itself
• Most libraries in the web ecosystem, including:
  • Flask
  • Django
  • Requests
  • SQLAlchemy
  • Werkzeug
• IPython
• Matplotlib
• Theano

Google format is used by:

• Many libraries in the ML ecosystem, including:
  • TensorFlow
  • PyTorch
• Google, presumably?

Additionally many other libraries in the numerical ecosystem use NumPy style, which is fairly similar to Google style.

I am currently leaning toward the Sphinx style, on the basis that it seems more common in the broader ecosystem, especially for web code, and that most of our Python code is in the web domain, so it'd maximize our consistency with the third-party libraries with which we most interact.

[nevsan]

IMO if any of those developers knew when they started their project that they could use Google style docstrings and still use docgen via Sphinx, there's no way they would have chosen Sphinx. I think new projects should use Google Style.

Also, Numpy uses it's own format, which is parseable by Sphinx and is also designed for readability in code, so although it's not an example of either, it's more similar in philosophy to Google Style.

[taion]

I don't think Sphinx suffers that much in usability, BTW.

The argument from consistency is just that if the vast majority of libraries we use also use Sphinx, then it's overall less cognitive load in dealing with different docstring formats if we do the same thing as there.

Basically not having to switch between Google style and Sphinx style if almost everything uses Sphinx.

[nathansilberman]

+1 for Google Style, I find the Google style for more readable and maintainable, which in this case is the biggest factor for me.

[cancan101]

So I think we decided here and in various in person meetings to use the Google style. That being said we never noted the resolution and closed this issue. Nor did we update the style guide itself.
@taion can I ask for your help in updating the style guide itself?

[taion]

The conclusion was that ML-related projects would use Google format and that web-related projects would use Sphinx.