Manually line wrapped many docstrings to conform to 88 characters per line or less. This wasn't a shortcoming of napoleon (or more accurately, the 'Google' string style I've been using) but actually black. I thought black would reflow docstrings by default, but actually that doesn't seem to be the case.
Should address the horizontal scrolling issue mentioned in #235 (also an issue for reading docstrings on GitHub). With the reflowed lines, the 'Google' style and the 'NumPy' style actually look pretty similar. Here is the official comparison with an admonition that a project should stick with a single docstyle.
If we are going to stick to a recommended line length of 88 columns (black) for all *.py files, then NumPy style might have the slight edge in terms of readability, since most of our docstrings are long and have complex arg types like tensors. As long as the docs compile accurately this is a low priority issue, but worth thinking about which direction we want our docstrings to drift towards in the natural course of editing.
Side note that Sphinx, even the latest v7, is terrible at giving useful errors on docstring formatting. Most of the errors raised during the docs build did not correspond to the site listed, but rather some other non-indented docstring in the same file.
napoleon(or more accurately, the 'Google' string style I've been using) but actuallyblack. I thoughtblackwould reflow docstrings by default, but actually that doesn't seem to be the case.Should address the horizontal scrolling issue mentioned in #235 (also an issue for reading docstrings on GitHub). With the reflowed lines, the 'Google' style and the 'NumPy' style actually look pretty similar. Here is the official comparison with an admonition that a project should stick with a single docstyle.
If we are going to stick to a recommended line length of 88 columns (black) for all
*.pyfiles, then NumPy style might have the slight edge in terms of readability, since most of our docstrings are long and have complex arg types like tensors. As long as the docs compile accurately this is a low priority issue, but worth thinking about which direction we want our docstrings to drift towards in the natural course of editing.Side note that Sphinx, even the latest v7, is terrible at giving useful errors on docstring formatting. Most of the errors raised during the docs build did not correspond to the site listed, but rather some other non-indented docstring in the same file.