Parsing See Also became too picky

[rgommers]

NumPy has a whole bunch of these in numpy/core/_add_newdocs.py, and with current master that crashes the doc build (0.8.0 works fine).

See Also
--------
The corresponding attribute of the derived class of interest. 

[rgommers]

This must be gh-172. It explicitly enumerates the valid See Also entries, but it overlooked this case. Arguably the entry of just a sentence is wrong, but there's nothing to cross-link instead. So the alternative is just to remove all those See Also sections. I'll do some more testing, if that's the only problem in numpy and scipy, then I guess I'll just clean up the numpy issue.

[jnothman]

I think we can try to be backwards compatible here. If there's no colon, that's hopefully a good heuristic.

[rgommers]

I think disallowing this is fine, the generated html was wrong before anyway: https://www.numpy.org/devdocs/reference/generated/numpy.generic.diagonal.html#numpy.generic.diagonal

The more annoying bit was that commas at the end of a list of function names now generates warnings. Here is what I needed to fix in numpy: numpy/numpy#13331.

Arguably the comma at the end of the first line here is okay:

func1, func2, func3, func4,
func5

[jnothman]

Sounds like we need a few more test cases. @pvanmulbregt

[pvanmulbregt]

I added the warning for the trailing comma in response to a reviewer's comments, but if the example above in #206 (comment) is acceptable, then the warning should be removed. Perhaps before adding more tests cases, the spec could be nailed down? As noted in #172 (comment) backticks require a role, and any function name with ~ requires backticks.

[jorisvandenbossche]

I also had this issue (the original reported, not the comma's) when testing the pandas docs with numpydoc master. I first wanted to open an issue here, but it turned out to be all templating mistakes in the pandas docs, so I am also OK with keep disallowing this and not trying to be backwards compatible (in the end, it catched errors in our docs)

[mattip]

A docstring containing the text "See also the corresponding attribute" is failing. Could the error message at least indicate which object's docstring is being parsed? The error message below is not very helpful

``` File ".../numpy/doc/sphinxext/numpydoc/docscrape.py", line 330, in _parse_see_also raise ParseError("%s is not a item name" % line) numpydoc.docscrape.ParseError: The corresponding attribute ... .\n\nSee Also\n--------\nThe corresponding attribute ...'

Exception occurred:
File "/home/matti/pypy_stuff/numpy/doc/sphinxext/numpydoc/docscrape.py", line 330, in _parse_see_also
raise ParseError("%s is not a item name" % line)

[rgommers]

@mattip I already commented on numpy/numpy#13331 (comment). See the \n after See Also in your traceback, you are just reporting the same thing I am in this issue.

Could the error message at least indicate which object's docstring is being parsed? The error message below is not very helpful

Yes this would be very useful. It's often really hard to do though, I think it's Sphinx' single worst issue - the whole debugging experience is awful.

[jnothman]

I added the warning for the trailing comma in response to a reviewer's comments

That was me :) Comma before colon seems a problem. Finishing the line with a comma is okay without colon (and ideally if the next line is not indented etc.).

[rgommers]

I first wanted to open an issue here, but it turned out to be all templating mistakes in the pandas docs, so I am also OK with keep disallowing this and not trying to be backwards compatible (in the end, it catched errors in our docs)

yes same here, +1 for being strict

I added the warning for the trailing comma in response to a reviewer's comments, but if the example above in #206 (comment) is acceptable, then the warning should be removed. Perhaps before adding more tests cases, the spec could be nailed down?

yes, we can more completely enumerate the allowed cases and add them to https://numpydoc.readthedocs.io/en/latest/format.html#sections

[rgommers]

After going through all of numpy and some of scipy, I didn't find any other types of cases. So for the spec I would propose:

1. All 4 cases in the description of What is the spec for "See Also" in docstrings? #170
2. The case with trailing comma: func1, func2, func3, func4,. (we should probably also allow trailing dot.

Anyone else have other cases?