Hundreds of Sphinx errors

[crusaderky]

sphinx-build emits a ton of errors that need to be polished out:

https://readthedocs.org/projects/xray/builds/ -> latest -> open last step

Options for the long term:

• Change the "Docs" azure pipelines job to crash if there are new failures. From past experience though, this should come together with a sensible way to whitelist errors that can't be fixed. This will severely slow down development as PRs will systematically fail on such a check.
• Add a task in the release process where, immediately before closing a release, the maintainer needs to manually go through the sphinx-build log and fix any new issues. This would be a major extra piece of work for the maintainer.

I am honestly not excited by either of the above. Alternative suggestions are welcome.

[dcherian]

Is there a sphinx or restructured text linter that we can run? e.g. https://github.com/PyCQA/doc8

[max-sixty]

Do these matter?

Do we know of examples of bad outcomes (e.g. hard-to-read docs)?

[crusaderky]

Yes. For example

http://xarray.pydata.org/en/stable/generated/xarray.Dataset.integrate.html#xarray.Dataset.integrate

The sphinx log states:

/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/latest/lib/python3.7/site-packages/xarray-0.14.0+37.g96cc2bc6-py3.7.egg/xarray/core/dataset.py:docstring of xarray.Dataset.integrate:12: WARNING: Unexpected indentation.

What I just now noticed is that several docstrings may be imported from numpy - which complicates everything.

[max-sixty]

The sphinx log states:

/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/latest/lib/python3.7/site-packages/xarray-0.14.0+37.g96cc2bc6-py3.7.egg/xarray/core/dataset.py:docstring of xarray.Dataset.integrate:12: WARNING: Unexpected indentation.

That's a good case...

[max-sixty]

I ran https://github.com/myint/docformatter on our code docformatter --in-place -r --wrap-summaries=88 . ; results here

But it doesn't solve many of our issues, which are around the sphinx docstrings

Happy to do a PR, but worry it's more churn than help?

[max-sixty]

Is there a sphinx or restructured text linter that we can run? e.g. https://github.com/PyCQA/doc8

Looks reasonable; though this is a checker rather than fixer

[keewis]

most of the nitpicky errors are raised because numpydoc tries to link to parameter types. We can define aliases and ignore terms like instance or words like of, see

https://github.com/mne-tools/mne-python/blob/da9cd19a9b65e792e2523f159820549ec6082f9d/doc/conf.py#L531-L616

for an example. We can also ignore nitpicky warnings using nitpick_ignore, but the normal warnings can't be selectively ignored (suppress_warnings ignores warning categories).

[keewis]

looks like I was wrong, numpydoc does not have much to do with this. The real culprit is napoleon: see sphinx-doc/sphinx#6861

[keewis]

this is not yet fully fixed, we still need to silence the nitpick warnings. That is blocked by the napoleon bug, though.