-
-
Notifications
You must be signed in to change notification settings - Fork 143
Treat __init__ differently than other methods #24
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
I, personally, prefer to illustrate how you call the class, i.e., join the Trying to sketch it, I would make it look like this:
Additionally, I think the attributes documentation section should be placed in Instance variables if I'm not mistaken. It would also make sense to include the inherited methods in maybe a collapsible section, something like 'Methods inherited from ClassFoo'. Similar to the way rustdoc illustrates which trait methods were implemented. I personally find this very useful. |
This looks particular and specific. 😬 Classes shown as callable in stead of their __inits__ can be easily achieved by overriding html.mako with a custom template. The API is pretty stable at this point. I'm certainly 👎 a command-line switch. Perhaps a config.mako tunable? Alternatively, we could go with a more fine-grained template for easier overriding part-wise. Listing Attributes as Instance variables would be trickier and would require manipulating the docstring and the Class object sooner in the pipeline. Numpydoc defines Attributes too, so I guess Attributes should always be listed as instance variables? But if one is documenting attributes in this way and not, say, pdoc-supported PEP-224 way, then they won't even have an Instance variables section (they'll just have their Attributes section)? Pdoc already lists inherited identifiers from ancestor Class objects it knows about (i.e. those that are defined within Modules that are being documented). |
Concerning the first point. What about changing the default template? Obviously this is a very subjective thing, but I personally think showing classes as callable makes sense, since this is the way you would write out the code when using this class. Thus I think it would make sense to adapt the default style into this direction. What is your opinion on this? Concerning the second paragraph. Just for clarification, I assume that attributes is a synonym for instance variable. Thus I think these two things should be placed in the same doc output, whether I like to place docstring next to the variables or in the class documentation in an 'Attributes' section. For the last part, I did not know that. What about making a bit more direct by including a way to see the actual documentation right in that very place, maybe initially hidden by a collapsible element? |
And Sphinx also does it this way. Good, I agree. This way, we can rid us of __init__ as the only method prefixed with an underscore. PR welcome. Don't know about something like PEP8 for style (:sweat_smile:), but following the conventions and serving the 95% use case certainly is the idea. |
Re Attributes listed as Instance variables, it is the same. But no one in their right mind uses both ways (intermixed) to document their class' members, so they will only ever end up with one of the two subsections. Attributes are technically Instance variables and we could parse them out and then attach them as |
Currently, there is a config.mako flag which you can tune: pdoc/pdoc/templates/config.mako Line 4 in 371a839
and which is then passed to pdoc.Class methods:Lines 169 to 172 in 371a839
This also lists inherited members, but they are dimmed (greyed out). |
@b52 Are you still interested in this (callable class instead of separate __init__) and enough to give it a shot? It'd be a good thing to have in the next release. 😁 |
@kernc Definitely, I was just occupied with finalizing a paper, but I might have a few hours this week, at latest the upcoming weekend. |
@kernc Got some pointers where to start for doing the |
I think maybe with a test containing a class with the two docstrings, expecting them concatenated. I guess most changes, shouldn't be a lot, really, would be in |
A little bit ad-hoc but seems to work. @b52, welcome to test current master on your project. |
@kernc Looks very good! I think it solves the problem nicely. |
Uh oh!
There was an error while loading. Please reload this page.
I use Google's docstring style by documenting
Class.__init__(self)
methods in theClass
docstring. Which means, I always have an__init__
method rendered without any documentation but the parameters and the default values. On the flip side, I have a largeClass
docstring rendered which contains explanations for all these parameters. Basically, everything is split up.What about an option to tackle this case including proper output?
For example, the one from

sklearn
where the__init__
signature is included in theClass
:The text was updated successfully, but these errors were encountered: