sjDan2003
commented
5 years ago After doing some investigation, I found the Sphinx documentation comparing Google Style vs Numpy Style here: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/ On this page, Sphinx mentions "Google style tends to be easier to read for short and simple docstrings, whereas NumPy style tends be easier to read for long and in-depth docstrings." In order to keep my functions unit testable and maintainable, I plan on short functions that only do one or two things. Therefore I would expect the docstrings for these functions to be short as well. This makes me lean toward the Google Style.
When comparing Google Style to Sphinx and Doxygen, I understand other articles explaining how easy it is to read the Google Style. Since Python is all about readability I will use the Google Style for docstrings.
I'm used to using Doxygen for C++, but while investigating how to apply Doxygen to Python, I found several other formats that are worth investigating. I'll document in this case the pros/cons of each and decide on one that I should use for this project.
Doxygen Supports multiple languages (C++, Python, etc)
Sphinx Uses reStructuredText (reST) format
Google Style reStructuredText (reST) format Seems easier to read than Sphinx or Doxygen, but Sphinx will support this style.
Numpy Style reStructuredText (reST) format Not sure if this offers any advantage over the Google Style