"Unexpected indentation" warnings from :members:

[asmeurer]

Since Sphinx updated to 1.7.0, our SymPy docs started failing. We have the setting enabled in our docs to turn warnings into errors.

We have gotten many errors like

Warning, treated as error:
/home/travis/build/sympy/sympy/sympy/codegen/cfunctions.py:docstring of sympy.codegen.cfunctions.exp2.eval:15:Unexpected indentation.
make: *** [html] Error 2

It turns out the source of the error has nothing to do with the method in question (which doesn't even have a docstring). The problem is that we used

.. automodule:: sympy.codegen.cfunctions
    :members:

instead of

.. automodule:: sympy.codegen.cfunctions

   :members:

This is requiring changes across our entire docs.

Now if Sphinx wants to require the newline here, that is fine. But the warning should be much more indicative of what the problem is. Also, quite annoyingly, it only warns about one issue at a time, so if you fix an issue and rebuild, it will warn about another one (and for whatever reason, Sphinx no longer caches the build??? Every build is done from scratch. This is even if I make no changes to anything).

I tested this against the master branch and it is the same result.

Upstream SymPy issue: sympy/sympy#14181

[asmeurer]

Apparently the "one warning at a time" behavior is a result of our use of the -W flag. It would be nice if all warnings were shown, even if they are interpreted as errors at the end of the build.

[tk0miya]

It seems this problem is a combination of two issues.

At first, autodoc_inherit_docstrings feature has been added since 1.7 (for details, please refer our manual).
As a result, a docstring of super class is also used for methods of subclasses automatically. For example, the docstring of sympy.codegen.cfunctions.exp2.eval() is same as sympy.core.function.Function.eval() (because exp2.eval() doesn't have its own docstring).

The next is an issue of markups. It seems docstrings of sympy is not correct. For example, here is the docstring of sympy.core.function.Function.eval().
https://github.com/sympy/sympy/blob/485a06bd38b69d15ab7a3c6a9a62931ebf98dbba/sympy/core/function.py#L280-L303

This docstring contains a example code, but it is not a code-block. So reST parser raises an error "Unexpected indentation.".
With 1.6.7, you can see same warning for autoclass:: sympy.core.function.Function.

.. autoclass:: sympy.core.function.Function
    :members:

root@572ebc7d25ed:/docs# make clean html
Removing everything under '_build'...
Running Sphinx v1.6.7
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
/usr/local/lib/python3.5/dist-packages/sympy/core/function.py:docstring of sympy.core.function.Function:6: WARNING: Unexpected section title.

Examples
========
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.

Build finished. The HTML pages are in _build/html.

From these issues, 1.7 causes "Unexpected indentation." warnings.
So I propose you to update your docstrings to correct reST. As a workaround, you can also disable autodoc_inherit_docstrings option. Then

On the other hand, your workaround is not correct.

.. automodule:: sympy.codegen.cfunctions

   :members:

This fix removes :members: option for automodule, and adds members field list as a content.
So members of modules will be vanished.

[asmeurer]

Thank you. My top priority was to fix CI build failures in master, so I didn't focus too much on the actual documentation build itself. I'll see if I can fix it correctly, if someone else doesn't do it first.

I think there is a bug here, which is that the error reporting from Sphinx is not very good. It would help a lot if it named the actual function that the docstring came from (Function.eval instead of exp2.eval). There's also the warnings as errors only appearing one at a time issue I mentioned, but that can be a separate issue if you want.

[tk0miya]

I think there is a bug here, which is that the error reporting from Sphinx is not very good. It would help a lot if it named the actual function that the docstring came from (Function.eval instead of exp2.eval).

Absolutely. The messages should be improved.

There's also the warnings as errors only appearing one at a time issue I mentioned, but that can be a separate issue if you want.

Yes please!