Location reporting returns useless information

[bsipocz]

Using numpydoc 0.7, the location of reporting seems to be broken, the currently provided information is useless yet too verbose.

  File "/Users/bsipocz/munka/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py", line 343, in _parse
    raise ValueError(msg)
ValueError: The section Examples appears twice in the docstring of None in None.

https://travis-ci.org/astropy/astroquery/jobs/287555157#L1742

I see that part of the code is already been refactored. I wonder if it's fixes my issue, what's your ETA for a new release?

Edit: I've just checked this with the current dev version, same error:

Exception occurred:
  File "/Users/bsipocz/munka/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py", line 358, in _error_location
    raise ValueError(msg)
ValueError: The section Examples appears twice in the docstring of None in None.

[amueller]

I don't think this is fixed (I introduced this in #95). It's not always useless, only if the information is not available at this point. The case were both are None is not caught and in that case we could get a more concise message. I don't think the necessary information is available at this point, but there might be a way to get around this.

[bsipocz]

I managed to get some info out when hacked that filename print to return self._parsed_data.

(We run into this case when we tried to use the docstring to generate parts of another one's. Clearly that utils function of ours needs upgrading, too).

[bsipocz]

Actually somewhat orthogonal, but in the same travis log there are examples for another message where a location would be most useful, too (though Return is at least grep-able for in the codebase).
UserWarning: Unknown section Return

[amueller]

@bsipocz that should have been fixed in #101. And PR certainly welcome to improve the current message / heuristics.

[bsipocz]

Arrg, I should have looked into the recent changes more carefully, and bundle that one into the recent astropy-helpers release.

[bsipocz]

I'll see whether I can cook up a PR quickly. Won't promise that it happen, but will look into it tonight.

[amueller]

I'm not 100% sure this was released yet? I feel the better error messages are mostly helpful for CI and maintainers - contributors tend not to look at the error messages in the doc build that much (unless you make the CI fail). So you can still benefit. I'm often switching between numpydoc branches when building the sklearn docs, at least for debugging purposes ;)

[amueller]

Development speed on numpydoc is pretty slow, so no rush, and if you get to it at any point, I'm sure many people would appreciate it :)

[bsipocz]

It wasn't released yet as of 0.7.
We actually make the docs builds fail on travis for most of the astropy projects, and also promote it in our package template, thus it will also bite maintainers less familiar with any of the infrastructure...

[bsipocz]

It will either happen some time soon (as now I still remember where and what the issue was), or probably never... 😉

[jnothman]

Now that Scikit-learn 0.19.1 is heading out the door, I would like to work towards getting numpydoc 0.8 out, as scikit-learn dev docs are currently a bit broken without b215bed. I figure I might as well try to fix a few of the easy issues here first.

[bsipocz]

I have a half-way ready hack from last weekend that I can try to finalize today (sadly my laptop died on Monday, so getting a backup solution up and ready took most of my time after that...).

[jnothman]

So I haven't understood: is this issue fixed in master, or not?

[bsipocz]

It's not yet fixed in master. I have one working solution (more like a hack) locally and will open a PR for it shortly.

[bsipocz]

See PR #123