Adding object infos to be able to raise meaningful location info

[bsipocz]

Fixes #115.

The example below has an invalid Return section in one of the doctrings, and in another one a duplicate Examples section. The invalid Return section is still warned over twice, but I take it as an improvement compared to the original 4 times.

I still need to add tests, and probably fix currently failing ones, but would first like to get the opinions whether you like this approach or not.

With master

updating environment: 176 added, 0 changed, 0 removed
/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py:366: UserWarning: Unknown section Return in the docstring of None in None.
  warn(msg)
/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py:366: UserWarning: Unknown section Return in the docstring of <function ExoplanetOrbitDatabaseClass.get_table at 0x108f7f0d0> in /Users/kgabor/bsipocz/devel/astroquery/build/lib.macosx-10.10-x86_64-3.5/astroquery/exoplanet_orbit_database/exoplanet_orbit_database.py.
  warn(msg)
/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py:366: UserWarning: Unknown section Return in the docstring of None in None.
  warn(msg)
/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py:366: UserWarning: Unknown section Return in the docstring of <function ExoplanetOrbitDatabaseClass.get_table at 0x108f7f0d0> in /Users/kgabor/bsipocz/devel/astroquery/build/lib.macosx-10.10-x86_64-3.5/astroquery/exoplanet_orbit_database/exoplanet_orbit_database.py.
  warn(msg)
reading sources... [ 44%] api/astroquery.skyview.SkyViewClass                  o_dictlass
Exception occurred:
  File "/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py", line 364, in _error_location
    raise ValueError(msg)
ValueError: The section Examples appears twice in the docstring of None in None.
The full traceback has been saved in /var/folders/8j/hn5sncjs31143t3kq4zxtg680000gn/T/sphinx-err-_hmijs60.log, if you want to report the issue to the developers.

With this PR:

updating environment: 176 added, 0 changed, 0 removed
/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py:360: UserWarning: Unknown section Return in the docstring of ExoplanetOrbitDatabaseClass.get_table in astroquery.exoplanet_orbit_database.exoplanet_orbit_database.
  warn(msg)
/Users/kgabor/bsipocz/devel/astroquery/astropy_helpers/astropy_helpers/extern/numpydoc/docscrape.py:360: UserWarning: Unknown section Return in the docstring of ExoplanetOrbitDatabaseClass.get_table in astroquery.exoplanet_orbit_database.exoplanet_orbit_database.
  warn(msg)
reading sources... [ 44%] api/astroquery.skyview.SkyViewClass                  o_dictlass
Exception occurred:
  File "/Users/kgabor/bsipocz/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 SkyViewClass.get_image_list in astroquery.skyview.core.
The full traceback has been saved in /var/folders/8j/hn5sncjs31143t3kq4zxtg680000gn/T/sphinx-err-a5gjyi1g.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.

[bsipocz]

Looking at the tests and current failures, I wonder whether it's better to make obj_info as a kwarg, with (None, None) as default.

[jnothman]

• NumpyDocString et al are used as public API. I think you need to keep config as the second parameter, and obj_info or whatever should be optional.
• Are you sure you want obj_info to be passed as a tuple rather than two separate parameters?

[bsipocz]

OK, I'll move it to be optional param. If you have a suggestion for a better name, it would be great.
I've opted it to be tuple, so it could be extended in the future if needed, but I don't have strong opinions on it and happy to adjust it based on suggestions.

[bsipocz]

I can't judge the seriousness of the 2nd test failure for the py3.6 cases, whether the fix in the PR has to be modified or rather the test.

[jnothman]

as far as I can tell, both those failures are true failures. You've somehow used fully qualified names for attribute reference where they used to be (and the test ensures they are) just the attribute name.

[jnothman]

However, if you test it on real class docs (e.g. adding to example.py and fixing #133 at the same time), and it produces functional output, we could consider changing the test.

[jnothman]

@bsipocz are you still working on this?

[bsipocz]

@jnothman - I don't have time atm, but will definitely plan to come back and finish this off in a few weeks time if that's OK for you.

[stefanv]

This patch is a huge improvement on the current error reporting. Can we merge as is and iterate from there?

[jnothman]

Well we should at least fix tests

[stefanv]

Yes, true that :)

[ChristianLieven]

Hey Numpydoc-Devs, is this still being worked on? I've just bumped into this issue today and finding out where this duplicate Notes field is would help me quite a lot:

Exception occurred:
  File "/anaconda/envs/test-memote/lib/python3.6/site-packages/numpydoc/docscrape.py", line 375, in _error_location
    raise ValueError(msg)
ValueError: The section Notes appears twice in the docstring of None in None.
The full traceback has been saved in /var/folders/k0/mbg69vgn5kq4155sqzwqyspw82jdws/T/sphinx-err-k_f8_745.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 2

[rgommers]

Hi @ChristianLieven, seems like it's close to ready but has stalled. It looks like we'd want to merge it if the tests are updated so they pass here. If you're interested in looking into that, that would be very helpful.

[bsipocz]

I'm sorry to drop the ball on this, but happy to see that the issue ultimately has been solved.