Skip to content

Document class, instance and module attributes #74

@leandro-lucarella-frequenz

Description

What's needed?

We need to document class attributes, as in the current state they are completely hidden to the user in the documentation.

Proposed solution

Use a string below the declaration of the class/instance/module variable:

global_variable: str = "I'm a global!"
"""A global variable.

This can have a long description too.
"""

class A:
    """A class."""

    class_attr: str
    """The attribute of the class (not an instance attribute!)."""

    def __init__(self, t: tuple[int, int]):
        self._priv_attr: tuple[int, int] = t
        """The private attribute.

        This will not be show in the generate documentation, so it should be done
        just as documentation for developers of this library.
        """

        self.pub_attr_with_init: tuple[int, int] = t
        """The public attribute.

        Public instance attributes must be documented in the `__init__` method and
        the type should be declared.  The type declaration and initialization should be
        in the same line, otherwise the documentation is not rendered properly. See
        the example below
        """"

        # BAD ⬇️
        self.some_docstr_attr_without_init: tuple[int, str]
        """This won't appear in the generated docs at all because there is no assignment!"

Long story

  • Class / instance attributes:

    • Attributes should be documented in general using docstrings, not the Attributes: section, as the Attribute: section doesn't produce ToC entries and doesn't extract a lot of info.

      class A:
          """A class.
      
          Attributes:
              some_attr_in_attributes: Attribute in `Attributes:`, shows nice in the
                  docs (the type is shown, no value is shown) but no ToC.
          """
      
          class_attr: str
          "This is marked as class attribute, not good."
      
          def __init__(self, t: tuple[int, int]):
              self.some_attr_in_attributes: tuple[int, int] = t
      
              self.some_docstr_attr_with_init: tuple[int, int] = t
              "This is marked as a instance attribute, but the value is shown out of context, not good."
      
              self.some_docstr_attr_without_init: tuple[int, str]
              "If we separate declaration from initialization, the declaration is not show, not good."
      
              self.some_docstr_attr_without_init = (2, "a")
      
              self.some_docstr_attr_without_init_doc_in_assign: tuple[int, str]
              self.some_good_attr = (2, "a")
              "But if we document the assignment, it is shown, but no type and out of context value, not good."

      image

    So it looks like there is no perfect solution, but using the style of some_docstr_attr_with_init seems to be the best approach.

  • Module attributes / type aliases

    I tried this:

    """Module docs.
    
    Attributes:
        SomeType: This is a type with lala.
    """
    
    SomeType = str

    And it produces:

    image

    While:

    """Module docs."""
    
    SomeType = str
    """This is a type with lala."""

    And it produces:

    image

    So the former is definitely the way to go.

Metadata

Metadata

Labels

part:docsAffects the documentationtype:enhancementNew feature or enhancement visitble to users

Type

No type

Projects

Status

Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions