Fix documentation build#2262
Conversation
The newly released `numpydoc` 1.2 emits many warnings about docstrings. The causes of these warnings are addressed by this commit and the documentation build should now succeed.
Codecov Report
@@ Coverage Diff @@
## main #2262 +/- ##
=======================================
Coverage 62.68% 62.69%
=======================================
Files 131 131
Lines 16818 16822 +4
=======================================
+ Hits 10542 10546 +4
Misses 6276 6276
Continue to review full report at Codecov.
|
|
|
||
| Parameters | ||
| ---------- | ||
| **kwargs |
There was a problem hiding this comment.
would you mind listing the params from above? to format lets you list them without the one-sentence description, and that is still better I think than listing kwargs only (I would rather prefer to remove the whole section that having kwargs only)
There was a problem hiding this comment.
I tried to fill out the docstring using the same mechanism that is used in pyvo.dal.sia2.py, but the documentation build now fails with
WARNING: py:obj reference target not found: pyvo.dam.obscore.POLARIZATION_STATES
WARNING: py:obj reference target not found: pyvo.dam.obscore.CALIBRATION_LEVELS
I'm not sure if this should be addressed here or if it's pyvo documentation that should be updated.
There was a problem hiding this comment.
I simply removed the offending links from the docstring for now because that seems to be the fastest way of fixing the documentation build without dropping the newly added parameter descriptions. If they don't cause problems for Sphinx at some point in the future then 03238e8 can be reverted.
|
Your documentation build is failing with the same Astrometry.net API key warning: Would it be possible for you to fold a fix for that into this branch or is it out of scope and need its own PR? |
The docstring of `astroquery.alma.AlmaClass.query_sia()` is constructed with the help of `pyvo.dal.sia2.SIA_PARAMETERS_DESC` constant, which however contains links that Sphinx is unable to resolve. These links are removed by this commit so that the documentation build can succeed.
|
@jaymedina - those warnings don't affect the docs build. I would love to have a way to have API keys and test accounts for all the services we provide access to, but unfortunately, that is not the case. Any suggestions for solutions are welcome. |
bsipocz
left a comment
There was a problem hiding this comment.
Perfect, rendered docs looks good now.
|
Thanks @eerovaher! |
The newly released
numpydoc1.2 emits many warnings about docstrings. The causes of these warnings are addressed by this pull request and the documentation build should now succeed.