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.

[max-sixty]

@keewis I'm guessing we're still stuck on this because of the Napoleon bug?

Your efforts to quash the previous warnings are laudable, and would be great if we can add tests to ensure they don't creep back in...