class named Parameters causes error

sphinx-doc / sphinx

The Sphinx documentation generator

Other

6.22k stars 2.04k forks source link

Hello Sphinx developers!

I've got a quirky one for you today. I work on pyvo, and we use sphinx for our document builds (like the rest of the astropy project). Recently, we had an interesting travis break when building our documents. I've been trying to fix it in this PR:

astropy/pyvo#189

This broke between builds with no changes to this file, which immediately made me think that some behavior somewhere has changed.

Originally, we thought it might have been due to the docstring starting with the word "Parameters", although even after taking out that docstring, we still had the same somewhat confusing error:

/home/travis/build/astropy/pyvo/build/lib/pyvo/io/uws/tree.py:docstring of pyvo.io.uws.tree.Parameters:22:Unexpected section title or transition.

After some fiddling, I found that the only way to get rid of this error was to rename the class to something other than Parameters.

From @bsipocz: I'm fairly certain this is more like a sphinx issue than a numpydoc one (I see the same error with numpydoc 0.8.0, using sphinx 2.2, but not with numpydoc 0.9.1 and sphinx 2.1.2). There seems to be some relevant looking changes in the diff between those versions, but I haven't yet pin pointed a PR for it.

bisect points to this commit: sphinx-doc/sphinx@1c088ec

Thanks to @jonathansick and @bsipocz for the help on nailing the particulars on this issue down.

Steps to reproduce the behavior:


$ git clone https://github.com/astropy/pyvo.git
$ cd pyvo
$ pip install sphinx_astropy
$ python setup.py build_docs -w

Expected behavior Expect no build error/warning as before, but now I get a build error

Your project https://github.com/astropy/pyvo

Screenshots If applicable, add screenshots to help explain your problem.

Environment info

OS: Linux, Mac, Travis
Python version: 3.7
Sphinx version: 2.2
Sphinx extensions: numpydoc, sphinx_astropy

I earlier thought it was a different numpydoc version, which has also changed in this build, but some excellent sleuthing by @bsipocz looks like it might be more on the Sphinx side. Here's the issue I have opened on numpydoc, which I'm closing out in favor of this one:

https://github.com/numpy/numpydoc/issues/237

Reproduced with following code:

# example.py
class Base:
    def __init__(self):
        """
        Parameters
        ----------
        types : sequence of types
            The types to accept.

        values : sequence, optional
            An initial set of values.
        """

class Parameters(Base):
    """Parameters element of a job."""
    def __init__(self):
        pass

# index.rst
.. automodule:: example
   :members:
   :undoc-members:
   :inherited-members:

# conf.py
extensions = ['sphinx.ext.autodoc']
autoclass_content = 'both'
autodoc_inherit_docstrings = True
autodoc_docstring_signature = True

This is caused by combination of settings and your source code.

Withautoclass_content = 'both, autodoc uses docstrings of both class and __init__() method for docstring of Parameters class.
With autodoc_inherit_docstrings = True (by default), autodoc considers a docstring of Parameters.__init__() as same as Base.__init__(). This was fixed at https://github.com/sphinx-doc/sphinx/commit/1c088ec.
With autodoc_docstring_signature = True (by default), autodoc considers the first line of docstring might be a signature.
In addition, the docstring of Base is written by numpy-style. So the Parameters keyword is placed at top of docstring.
As a result, the Parameters keyword is stripped by autodoc. But the underline of Parameters section is still remaining on docstring. It causes syntax error of reStructuredText.

I think this is unfortunate accident, not a bug. To avoid the error, please disable one of the options or put empty docstring to the Parameter.__init__().

sphinx-doc / sphinx

class named Parameters causes error #6753