SNEWS2 / snewpy

A Python package for working with supernova neutrinos
https://snewpy.readthedocs.io
BSD 3-Clause "New" or "Revised" License
26 stars 19 forks source link

Model's construction documentation is not shown #246

Closed Sheshuk closed 8 months ago

Sheshuk commented 1 year ago

Looking at the models.ccsn.Nakazato_2013 model, I see a nice automated docstring for the __new__ method. However this doc is not shown by default (at least for me, using jupyter):

>>> from snewpy.models import ccsn
>>> ccsn.Nakazato_2013?
Init signature:
ccsn.Nakazato_2013(
    filename=None,
    *,
    progenitor_mass=None,
    revival_time=None,
    metallicity=None,
    eos=None,
)
Docstring:     
Model based on simulations from Nakazato et al., ApJ S 205:2
(2013), ApJ 804:75 (2015), PASJ 73:639 (2021). See also http://asphwww.ph.noda.tus.ac.jp/snn/.
File:           ~/work/SNEWS/snewpy/python/snewpy/models/ccsn.py
Type:           ABCMeta
Subclasses: 

And if I try to autocomplete with tab, I get the same result. So all the nice descriptions are not visible to the user, unless he inspects ccsn.Nakazato_2013.__new__?

I think the cause here is that the documentation to __new__ is not shown by default (python doesn't expect user to access this method explicitly)

JostMigenda commented 1 year ago

Hmm … that’s not good.

When Spencer and I worked on this, we did check that the __new__ docstring got included in the Sphinx-generated documentation; and of course it is also shown when running help(ccsn.Nakazato_2013). But we didn’t check Jupyter’s ? apparently.

I find it a bit surprising that Jupyter clearly recognizes the __new__ method and extracts the “Init signature” from that, but it doesn’t include the docstring. Would it include the docstring from the __init__ method? If so, I wonder if it’s worth reporting this difference between __new__ and __init__ as an issue with Jupyter?