class named Parameters causes error

[cbanek]

Hello numpydoc developers!

I've got a quirky one for you today. I work on pyvo, and we use numpydoc 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

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 (named Parameters, one of the keywords for the numpydoc) to something other than Parameters.

This behavior seems to be a recent change between numpydoc 0.9.0 (works fine) and 0.9.1 (gives this error). I'm not sure if this is intended, unintended, or if there is a better way of handling this, but I thought you should know, since other codebases may have a class named Parameters.

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

[bsipocz]

@cbanek - 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.

[bsipocz]

bisect points to this commit, I don't yet see how it's causing the failure, but suggest to close this issue and open another one for sphinx. sphinx-doc/sphinx@1c088ec

[cbanek]

Yep you're right, I'm wondering if maybe my sphinx version changed when I was doing the repro, but I see what you're seeing.

[cbanek]

Closing in favor of sphinx-doc/sphinx#6753