Instance variables set using __pdoc__ don't work

[JPLeBreton]

If I have something like:

class Foo:
    a,b,c = 0, 1, 2
    def __init__(self):
        self.d, self.e, self.f = 3, 4, 5

Class variables a,b,c show up in the generated docs, but instance variables d,e,f do not.
Expected result: instance variables declared in this manner should show up in generated docs.

[BurntSushi]

Instance variables are detected by parsing the AST. I'd prefer a lower tech solution. You must write each instance variable on its own line, or modify __pdoc__ directly.

[JPLeBreton]

Okay, thanks. I'm trying to work out how to do the latter; nothing I try is working. From the example above, would I do this?

__pdoc__ = {}
__pdoc__['Foo.d'] = "Docstring for Foo's d instance variable."
class Foo:
    a,b,c = 0, 1, 2
    def __init__(self):
        self.d, self.e, self.f = 3, 4, 5

or __pdoc__['mymodule.Foo.d']? or something else?

[BurntSushi]

From the docs:

Thirdly and finally, docstrings can be overrided with a special pdoc dictionary that pdoc inspects if it exists. The keys of pdoc should be identifiers within the scope of the module. (In the case of an instance variable self.variable for class A, its module identifier would be A.variable.) The values of pdoc should be docstrings.

So Foo.d should work.

It looks like your example doesn't work, which means this is probably a bug. It looks like putting each instance variable on its own line does work though.

[JPLeBreton]

Thanks. Shall I file a bug for that related-but-separate issue?

[BurntSushi]

This issue is fine. I renamed the title. I don't think I'll ever support multiple instance variables defined on the same line.

[DewaldDeJager]

+1 for adding support for multiple instance variables defined on the same line. Wanted to see if there wasn't an issue on this already before opening one. My use case:

(self.var1, self.var2, self.var3) = self.method_that_returns_tuple()

Hopefully in future I can get some time and submit a pull request with this added. Thanks for the great tool, Andrew!

[mhils]

Hi, current pdoc maintainer here! The recommended workaround to do this now is to document your variables on the class itself, see
https://pdoc.dev/docs/pdoc.html#document-variables.

I'll close this here as we have (at least temporarily) removed __pdoc__.

[daniele-niero]

Is there any way, template, macros, whatever, to force any instance variable to show up in the documentation regardless their docstring status?

Sometimes this variables don't need any explanation but having them in the documentation is needed to give the users all the clear information they need

A very simple example that come to mind is a Vector class

class Vector:
    def __init__(self):
        self.x = 0.0
        self.y = 0.0
        self.z = 0.0

Now x, y and z won't appear in the documentation, unless I document them. But should I really have to document them? and with what?

class Vector:
    def __init__(self):
        self.x = 0.0
        """ The vector's x component"""
        self.y = 0.0
        """ The vector's y component"""
        self.z = 0.0
        """ The vector's z component"""

In my opinion It is kind of redundant.

[mhils]

You can write a template that overrides is_public, see for example https://github.com/mitmproxy/pdoc/blob/main/examples/custom-template/module.html.jinja2.

Specifically:

{% macro is_public(doc) %}
    {% if doc.kind == "variable" %}
        true
    {% else %}
        {{ default_is_public(doc) }}
    {% endif %}
{% endmacro %}

[daniele-niero]

This doesn't work, the problem is that instance or class variables seems not being picked up by pdoc's api at all, unless they are commented, so the never get passed to that macro in the first place.

I tried and they are not included in what is returned by methods such as member, own_members etc.

And as a small note, they are public in my example, so is not really that the issue. They should be picked up like any other member. A method, for instance, even if not documented, ends up in the documentation

Also probably worth mentioning, I'm using pdoc version 12.2.0 installed on python 3.7 through pip

[mhils]

True - we didn't pick them up so far as they are excluded in the default template. #461 fixes this!

[daniele-niero]

Thank you, works like a charm :)