-
Notifications
You must be signed in to change notification settings - Fork 20
Closed
Labels
part:docsAffects the documentationAffects the documentationtype:enhancementNew feature or enhancement visitble to usersNew feature or enhancement visitble to users
Milestone
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 theAttribute: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."
So it looks like there is no perfect solution, but using the style of
some_docstr_attr_with_initseems 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:
While:
"""Module docs.""" SomeType = str """This is a type with lala."""
And it produces:
So the former is definitely the way to go.
Metadata
Metadata
Assignees
Labels
part:docsAffects the documentationAffects the documentationtype:enhancementNew feature or enhancement visitble to usersNew feature or enhancement visitble to users
Type
Projects
Status
Done


