Improve Documentation

AUTHORS.rst

@@ -1,9 +1,30 @@
 ============
-Contributors
+Contributing
 ============
 
+We're thrilled that you're interested in contributing to the BO4E (Business Object for Energy) project.
+This is an open-source project and we love to see new contributors.
+
+Our project has already benefited from the contributions of amazing developers.
+We're excited to see your name join this list!
+
+Whether you're fixing bugs, adding new features, or improving documentation, your work will make a significant impact.
+
+Please make sure to read our [Contributing Guide](LINK_TO_CONTRIBUTING_GUIDE) and feel free to reach out if you have any questions or need help.
+Just open an issue or send us an email.
+We can also provide you with an invitation link to our Slack workspace.
+
+Thank you for your interest in BO4E, and we look forward to seeing your contributions!
+
+Contributors
+------------
+
+The following people have contributed to the development of this project:
+
 * Kevin Krechan <kevin.krechan@hochfrequenz.de>
 * Leon Haffmans <leon.haffmans@hochfrequenz.de>
 * Annika Schlögl <annika.schloegl@hochfrequenz.de>
 * Franziska Vesely <franziska.vesely@hochfrequenz.de>
 * Konstantin Klein <konstantin.klein@hochfrequenz.de>
+* Tim Steufmehl <tim.steufmehl@enet.eu>
+* Kevin Frenken <kevin.frenken@enet.eu>

LICENSE.rst

@@ -1,7 +1,5 @@
 MIT License
 
-Copyright (c) 2021 Hochfrequenz Unternehmensberatung GmbH
-
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

docs/changelog.rst

@@ -1,8 +1,14 @@
 .. _changes:
 
-================
+=========
+Changelog
+=========
+
+You can find the changelog on the ` GitHub Release page<https://github.com/bo4e/BO4E-python/releases>`_.
+
+=============
 Compatibility
-================
+=============
 
 The table below shows the compatibility matrix of the last BO4E versions.
 You can also download the compatibility matrix as CSV file `here <_static/tables/compatibility_matrix.csv>`_.
@@ -34,5 +40,3 @@ Legend:
 .. csv-table:: Compatibility matrix
    :file: _static/tables/compatibility_matrix.csv
    :header-rows: 1
-
-.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -241,10 +241,10 @@
 # html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-# html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
+html_show_copyright = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the

docs/contributing_guide.rst

@@ -0,0 +1,133 @@
+How to Contribute Code
+======================
+
+This document describes how the BO4E Python implementation is written and what to watch out for.
+
+Technical Setup in your IDE
+===========================
+
+We're using tox. Please follow the instructions in our `Python Template Repository <https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine>`_. Feel free to open an issue if you run into any kind of problems.
+
+Coding Style and Guidelines
+===========================
+
+General Rules
+-------------
+
+- We use (and enforce in the CI):
+  - black for formatting
+  - pylint for linting
+  - mypy for static type checking
+  - pytest for unittests
+  - Sphinx and Plantuml (and kroki web service) for documentation
+- Technical Documentation is in English; For example: "Don't use the builtin validator here because …"
+- But data model docstrings are in German; For example: "Ist das Ende nicht gesetzt, so ist der Zeitraum als offen zu verstehen."
+- Docstrings should not be trivial/useless
+  - Bad: "Energiemenge ist eine Klasse zur Abbildung von Energiemengen." ❌ (no shit Sherlock)
+  - Good: "Eine Energiemenge ordnet einer :class:`Marktlokation` oder :class:`Messlokation`, die über die `lokations_id` referenziert werden, einen oder mehrere Energieverbräuche zu." ✔
+- Only sentences have a full stop at the end.
+- We use ``snake_case`` internally but serialize as ``camelCase`` by overriding the ``data_key`` property of the schema fields.
+
+How to Define an ENUM?
+----------------------
+
+All Enums inherit from ``bo4e.enum.StrEnum``. The latter is just a usual Enum with a ``str`` mixin (see `the official docs <https://docs.python.org/3/library/enum.html?highlight=strenum#others>`_ for details). This allows us to precisely define how an enum value will be serialized. All enum values have UPPER_CASE names.
+
+.. code-block:: python
+
+   # pylint:disable=missing-module-docstring
+
+   from bo4e.enum.strenum import StrEnum
+
+   class MyBo4eEnum(StrEnum):
+       """
+       Hier sollte ein deutscher Text stehen, der Sinn und Zweck des Enums beschreibt.
+       """
+
+       FOO = "FOO" #: FOO ist, wenn der Himmel blau ist
+       BAR = "BAR"
+       """
+       Der Docstring für BAR kann auch hier drunter stehen, wenn er besonders lang ist und mehr sagen will,
+       als dass BAR für die grüne Wiese steht. Denn manchmal braucht es mehr als hundert Zeichen.
+       """
+       EIGENSCHAFT_0815 = "0815" #: manchmal heißen eigenschaften anders (EIGENSCHAFT_0815) als sie serialisiert werden ("0815")
+       # this typically happens for annoying enum values that contains "-" or start with digits
+
+How to Define COMs or BOs
+-------------------------
+
+All COMponents inherit from ``bo4e.com.com.COM``. All Business Objects inherit from ``bo4e.bo.geschaeftsobjekt.Geschaeftsobjekt``.
+
+For data validation and de/serialization we use `pydantic <https://pydantic-docs.helpmanual.io/>`_.
+
+.. code-block:: python
+
+   """
+   Give the module a docstring to describe what it contains
+   """
+
+   from pydantic import validator
+
+   from datetime import datetime
+   from typing import Optional, Dict, Any
+
+   from ..bo.geschaeftsobjekt import Geschaeftsobjekt
+   from ..com.menge import Menge
+   from ..enum.typ import BoTyp
+
+   # pylint: disable=too-few-public-methods
+   class MeinBo(Geschaeftsobjekt):
+       """
+       MeinBo ist ein ganz besonderes Business Objekt.
+       Es kommt nur bei meinem Strom-Lieferanten zum Einsatz und beschreibt dort all die tollen Eigenschaften, die mein Verbrauchsverhalten hat.
+       """
+
+       typ: Annotated[Optional[Typ], Field(alias="_typ")] = Typ.MEINBO
+
+       #: Der Lieferbeginn beschreibt den Zeitpunkt ab dem (inklusiv) mich ein Versorger seinen Kunden nennen darf
+       lieferbeginn: Optional[datetime] = None
+
+       anzahl_freudenspruenge: Optional[int] = None
+       """
+       Anzahl Freudensprünge beschreibt, wie oft der CEO des Stromkonzerns in die Luft gesprungen ist, als ich den Vertrag unterschrieben habe.
+       """
+
+       #: Menge (Elektrische Energie oder Gas oder Wärme), die ich zum Lieferbeginn umsonst erhalte
+       freimenge: Optional[Menge] = None
+
+       # we can help you with anything you might be missing or unable to implement.
+       # ToDo comments are just fine.
+       # You don't need to be a perfect programmer to contribute to bo4e :)
+
+Unittests
+---------
+
+Ideally provide unittests that show:
+
+- that the BO/COM can be instantiated
+  - with only the required attributes
+  - with all attributes
+- can be serialized and deserialized again
+  - with only the required attributes
+  - with all attributes
+
+Therefore, copy one of the existing "roundtrip" tests, see f.e. ``TestTarifeinschraenkung``.
+
+Pull Request
+============
+
+Open a Pull Request against the main/default branch of this repository. We'd appreciate if you allowed maintainer edits.
+
+Release Workflow
+================
+
+- Check with tox all tests and linting: ``tox``
+- Check with tox if the packaging works fine: ``tox -e test_packaging``
+- Squash Merge all your changes you would like to have in the release into the main/default branch
+- Check that all GitHub Actions for tests and linting do pass (should be automatically enforced for PRs against main)
+- Go to the repositorys right sidebar and click on `Draft a new release <https://github.com/Hochfrequenz/BO4E-python/releases/new>`_
+- Write in the *Tag version* field and in the *Release title* your new version, i.e. ``v0.0.6``
+- Add a description to the release (or just autogenerate the change log which will be fine for 95% of cases)
+- Publish the release
+
+There is a GitHub Action which gets triggered by a release event. It will run all default tests with tox. If they pass, it will take the tag title to replace the version information in the *setup.cfg* file. After checking the package with ``twine check`` it will finally upload the new package release.

docs/fundamentals.rst

@@ -0,0 +1,13 @@
+============
+Fundamentals
+============
+
+The BO4E data model is constructed around three main parts: Business Objects, Components, and Enumerations.
+
+**Business Objects** and **Components** are the primary building blocks of the data model.
+They inherit from a main Business Object and a main Component respectively.
+These main objects contain meta data fields such as `_id`, `_typ`, and `_version` that are common to all Business Objects and Components.
+
+**Enumerations** are used to represent a set of named values in the data model, providing a way to enforce specific values for a field.
+
+This structure allows for a high degree of flexibility and extensibility, enabling the data model to adapt to the evolving needs of the German energy market.