Rework with pydantic + svg images in documentation (#380)

### Quick summary of important changes:
- switched from marshmallow + attr / attrs to [pydantic](https://pydantic-docs.helpmanual.io/)
    - [data validation](https://pydantic-docs.helpmanual.io/usage/validators/) and de/serialization will be processed by pydantic
        - serialization with `<instance>.json(by_alias=True, ensure_ascii=False)`
        - deserialization with `<class>.parse_raw(<json_string>)`
        - note: pydantic comes with some [useful types](https://pydantic-docs.helpmanual.io/usage/types/)
    - now schema-classes aren't neccessary anymore -> removed
    - json-schemas for readthedocs are created via `.schema_json()`
        - important note: json-schema files got renamed from `<classname>Schema.json` to `<classname>.json`
    - important note: Now e.g. `"2.4"` would be accepted as `Decimal` if the string is parsable (and it will be parsed!) -> a field with e.g. `Decimal` type hint will always be `Decimal`. But it can be set/initialized through e.g. a string if the string is parsable into a `Decimal`. However, the type checker would cry if you try this without "type casting" :)
- auto creation of uml-diagrams and integration with sphinx
    - when building the docs local via `tox -e docs` or `tox`, the generated [Plantuml](https://plantuml.com/de/) (Java software)-files will be sent to [kroki.io](https://kroki.io) web service in order to generate the svg images. This means, it will be painfully slow with ICE WLAN :)
    - uml-diagrams are generated for all classes in `bo` and `com` on runtime via: `docs/conf.py` -> `docs/uml.py`  -> creates `*.puml` files in `docs/api/uml` -> sent to kroki.io and get svg -> save to `_static` folder
    - `*.svg` files can be included in docstrings via an object tag, e.g. `<object data="../_static/images/bo4e/bo/Marktlokation.svg" type="image/svg+xml"></object>`
    - Note: The links inside the svgs are absolute. If you want svg files with other base URIs (or no base URIs, just relative paths), you just have to change `LINK_BASE_URI` in `docs/uml.py`

Co-authored-by: Leon Haffmans <leon.haffmans@hochfrequenz.de>
Co-authored-by: konstantin <konstantin.klein@hochfrequenz.de>

Author: 3 people

.gitignore

@@ -162,3 +162,8 @@ Icon
 Network Trash Folder
 Temporary Items
 .apdisk
+
+# This directory rebuilds on 'tox -e docs' therefore not needed in repo
+docs/api
+docs/plantuml.jar
+docs/_static/images

CONTRIBUTING.md

@@ -17,20 +17,20 @@ Feel free to open an issue if you run into any kind of problems.
   - pylint for linting
   - mypy for static type checking
   - pytest for unittests
-  - Sphinx for documentation
+  - 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 fullstop at the end.
+- 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 precisly define how an enum value will be serialized.
+This allows us to precisely define how an enum value will be serialized.
 All enum values have UPPER_CASE names.
 
 ```python
@@ -56,80 +56,60 @@ class MyBo4eEnum(StrEnum):
 
 ### How to Define `COM`s or `BO`s
 
-All COMponents inherit from `bo4e.com.COM`.
-All Business Objects inherit from `bo4e.bo.Geschaeftsobjekt`.
+All COMponents inherit from `bo4e.com.com.COM`.
+All Business Objects inherit from `bo4e.bo.geschaeftsobjekt.Geschaeftsobjekt`.
 
-The classes are defined with the help of [`attrs`](https://www.attrs.org/).
-
-For the de/serialization we use [`marshmallow`](https://marshmallow.readthedocs.io/).
-Each Python attr-decorated class comes with a corresponding marshmallow schema.
-
-All COMpontent schemas inherit from `bo4e.com.com.COMSchema`.
-All Business Object schemas inherit from `bo4e.bo.Geschaeftsobjekt.GeschaeftsobjektSchema`.
+For data validation and de/serialization we use [`pydantic`](https://pydantic-docs.helpmanual.io/).
 
 ```python
 """
 Give the module a docstring to describe what it contains
 """
 
-from datetime import datetime
-from typing import Optional
+from pydantic import validator
 
-import attr
-from marshmallow import fields
+from datetime import datetime
+from typing import Optional, Dict, Any
 
-from bo4e.bo.geschaeftsobjekt import Geschaeftsobjekt, GeschaeftsobjektSchema
-from bo4e.com.menge import Menge, MengeSchema
+from bo4e.bo.geschaeftsobjekt import Geschaeftsobjekt
+from bo4e.com.menge import Menge
 from bo4e.enum.botyp import BoTyp
 
 
 # pylint: disable=too-few-public-methods
-@attr.s(auto_attribs=True, kw_only=True)
 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 Eingeschaften, die mein Verbrauchsverhalten hat.
+    Es kommt nur bei meinem Strom-Lieferanten zum Einsatz und beschreibt dort all die tollen Eigenschaften, die mein Verbrauchsverhalten hat.
     """
 
-    bo_typ: BoTyp = attr.ib(default=BoTyp.MEINBO)
+    bo_typ: BoTyp = BoTyp.MEINBO
+
     # required attributes
+
     #: Der Lieferbeginn beschreibt den Zeitpunkt ab dem (inklusiv) mich ein Versorger seinen Kunden nennen darf
-    lieferbeginn: datetime = attr.ib(validator=attr.validators.instance_of(datetime))
+    lieferbeginn: datetime
 
-    anzahl_freudenspruenge: int = attr.ib(validator=attr.validators.instance_of(int))
+    anzahl_freudenspruenge: int
     """
     Anzahl Freudensprünge beschreibt, wie oft der CEO des Stromkonzerns in die Luft gesprungen ist, als ich den Vertrag unterschrieben habe.
     Dieser Wert sollte im Normalfall mindestens 5 sein.
     """
-    # todo: write a validator for anzahl_freudensprunge to be >5 and raise a ValidationError otherwise
+    # pylint:disable=unused-argument, no-self-argument
+    @validator("anzahl_freudenspruenge")
+    def validate_freudenspruenge(cls, anzahl_freudenspruenge: int, values: Dict[str, Any]) -> int:
+        if anzahl_freudenspruenge <= 5:
+            raise ValueError("You are not hyped enough. Do more than 5 joyful leaps.")
+        return anzahl_freudenspruenge
+
     # 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 :)
 
-    #: Optionale Menge (Elektrische Energie oder Gas oder Wärme), die ich zum Lieferbeginn umsonst erhalte
-    freimenge: Optional[Menge] = attr.ib(
-        validator=attr.validators.optional(attr.validators.instance_of(Menge)), default=None
-    )
-
-
-class MeinBoSchema(GeschaeftsobjektSchema):
-    """
-    Schema for de-/serialization of :class:`MeinBo`
-    """
-
-    # you don't need to copy paste the docstrings to the schema
-
-    class_name = MeinBo
-    # this is used so that the Python object created on deserialization/loading has the correct type
-
-    # required attributes
-    lieferbeginn = fields.DateTime()
-    # the camelCase serialization is enforced via he data_key kwarg
-    anzahl_freudenspruenge = fields.Int(data_key="anzahlFreudenspruenge")
-
     # optional attributes
-    # when nesting you need to reference the schema here (not Menge but MengeSchema!)
-    freimenge = fields.Nested(MengeSchema, load_default=None)
+
+    #: Optionale Menge (Elektrische Energie oder Gas oder Wärme), die ich zum Lieferbeginn umsonst erhalte
+    freimenge: Optional[Menge] = None
 
 ```
 
@@ -144,7 +124,7 @@ Ideally provide unittests that show:
   - with only the required attributes
   - with all attributes
 
-Therefore copy one of the existing "roundtrip" tests, see f.e. `TestTarifeinschraenkung`.
+Therefore, copy one of the existing "roundtrip" tests, see f.e. `TestTarifeinschraenkung`.
 
 ## Pull Request
 
@@ -153,16 +133,16 @@ We'd appreciate if you allowed maintainer edits.
 
 ## Release Workflow
 
-- Check with tox all tests and lintings: `tox`
+- 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 side bar and click on "[Draft a new release](https://github.com/Hochfrequenz/BO4E-python/releases/new)"
+- 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 describtion to the release (or just autogenerate the change log which will be fine for 95% of cases)
+- 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.
+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/conf.py

@@ -18,7 +18,11 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
+from pathlib import Path
+
 sys.path.insert(0, os.path.join(__location__, "../src"))
+sys.path.insert(0, os.path.join(__location__, "../docs"))
+from uml import PlantUMLNetwork, build_network, compile_files_kroki, write_class_umls
 
 # -- Run sphinx-apidoc ------------------------------------------------------
 # This hack is necessary since RTD does not issue `sphinx-apidoc` before running
@@ -251,7 +255,7 @@
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+# (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
     (
         "index",
@@ -288,3 +292,13 @@
     "sphinx": ("http://www.sphinx-doc.org/en/stable", None),
     "python": ("https://docs.python.org/" + python_version, None),
 }
+
+# Create UML diagrams in plantuml format. Compile these into svg files into the _static folder.
+# See docs/uml.py for more details.
+_exec_plantuml = Path(__location__) / "plantuml.jar"
+_network, _namespaces_to_parse = build_network(Path(module_dir), PlantUMLNetwork)
+write_class_umls(_network, _namespaces_to_parse, Path(output_dir) / "uml")
+print("Created uml files.")
+
+compile_files_kroki(Path(output_dir) / "uml", Path(output_dir).parent / "_static" / "images")
+print(f"Compiled uml files into svg using kroki.")