Repository navigation
astropy autodoc templates should document __call__ method #1817
Description
From the dev list:
Q: (@rhewett)
- Is it possible to modify the astropy autodoc templates to document the
__call__method? ... I've tried adding the:special-functions:directive to the
class.rst template, with no success. It might be nice for Astropy to have
this anyway, as there are a few functors, especially in modeling, that don't
have their call signatures in the documentation.
A: (@eteq)
This is a very good point. I think the fact that
:special-functions:doesn't work is probably a bug of some sort...
But regardless, it does make sense to document__call__whenever it
is present.
Activity
eteq commentedon Nov 22, 2013
I'm milestoning it to v0.3.1 (and assigning it to myself), as it's mainly a documentation fix.
cdeil commentedon Feb 22, 2014
@embray @nden @astrofrog Does anyone know how to do this?
At the moment the API docs for models and fitters are pretty bad, because the
__call__method is not included in the documentation.See e.g. the SLSQPFitter or the Beta1D or Parametric1DModel docs.
astrofrog commentedon Feb 24, 2014
@cdeil - It might just be a case of adding
__call__to the list of private methods to include on lines 466 and 467 ofastropy/sphinx/ext/automodsumm.py:I don't have time to test this - maybe you could try?
cdeil commentedon Feb 26, 2014
@astrofrog I tried your suggestion and it does add
__call__to the API docs (see here for all classes that have this and how__call__appears in their docs).So do we want this for all classes as part of the HTML docs?
I'd be 👍 and can make a PR if we do ... the change is at https://github.com/cdeil/astropy/compare/issue_1817
Add __call__ to Sphinx API docs (fixes astropy#1817)
astrofrog commentedon Feb 26, 2014
@cdeil - that probably makes sense. Do you see any classes where this is being done but does not make sense?
cdeil commentedon Feb 26, 2014
I see some
__call__methods without a docstring (i.e. the user has no indication of what they do and what their inputs / outputs are), but I think all of those__call__methods should be documented for users.Except maybe SAMPMsgReplierWrapper.call ... there I have no idea what it does.
astrofrog commentedon Feb 26, 2014
@cdeil - I haven't figured out what that class does. I'll follow up with Luigi.
cdeil commentedon Feb 26, 2014
PR: #2135
Add __call__ to Sphinx API docs (fixes astropy#1817)
Add __call__ to Sphinx API docs (fixes astropy#1817)
cdeil commentedon Mar 3, 2014
This fix is still not reflected in the online docs:
http://docs.astropy.org/en/latest/search.html?q=__call__
@astrofrog or @eteq Please wipe readthedocs to trigger a clean docs re-built there.
eteq commentedon Mar 3, 2014
@cdeil - I just tried to do this now, but nothing happened... and I also can't get it to manually build. It may be that there's some sort of trouble on the RTD side? Will try again in a bit.
eteq commentedon Mar 4, 2014
Looks like RTD finally managed to pull itself together. If you look at http://astropy.readthedocs.org/en/latest/api/astropy.modeling.Model.html you'll see it now features a
__call__method. Thanks for pointing this out, @cdeil.Add __call__ to Sphinx API docs (fixes astropy#1817)