Coding for documentation
This documentation is build from written materials as well as from the source code. The written materials augment what is available in the source code and provide examples or howto’s. Using good commenting practices in the code greatly helps with improving this documentation as well.
Autodoc
The module is configured to use Sphynx to auto-document the source code and utilizes the Napoleon extension to parse Numpy and Google style docstrings. In your IDE use tools like autoDocstring for VSCode to generate sphinx-notype docstring skeletons. [1]
Docstring
Example of a docstring generated with autoDoc and included in this documentation and types automatically added:
@classmethod
def from_v1_api(cls, data: dict[str, Any]) -> EnvoySystemProduction:
"""Initialize from the V1 API.
:param data: JSON reply from api/v1/production endpoint
:return: Lifetime, last seven days, todays energy and current power for solar production
"""
Attributes
Postfix attributes with a #: Comment
to provide descriptions that are used in generated documentation
@dataclass(slots=True)
class EnvoySystemProduction:
"""Model for the Envoy's production data."""
watt_hours_lifetime: int #: Lifetime Energy produced
watt_hours_last_7_days: int #: Energy produced in previous 7 days (not including today)
watt_hours_today: int #: Energy produced since start of day
watts_now: int #: Current Power production
Similar for enumerations
class SupportedFeatures(enum.IntFlag):
""" Flags for each feature supported
:param enum: Feature Name
"""
INVERTERS = 1 #: Can report Invertrs
METERING = 2 #: Can report CT Meter data