fix(docs): Fix doc strings such that the docs and the json-schemas don't differ (#949)

* Unify doc string style for `bo` and `com`

* Unify doc string style with `enum`

* Only use pydantics docstring feature instead of custom logic

* 🔥

Author: lord-haffi

src/bo4e/bo/angebot.py

@@ -39,27 +39,31 @@ class Angebot(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.ANGEBOT], Field(alias="_typ")] = Typ.ANGEBOT
-    #: Eindeutige Nummer des Angebotes
     angebotsnummer: Optional[str] = None
-    #: Erstellungsdatum des Angebots
+    """Eindeutige Nummer des Angebotes"""
     angebotsdatum: Optional[pydantic.AwareDatetime] = None
-    #: Sparte, für die das Angebot abgegeben wird (Strom/Gas)
+    """Erstellungsdatum des Angebots"""
     sparte: Optional["Sparte"] = None
-    #: Ersteller des Angebots
+    """Sparte, für die das Angebot abgegeben wird (Strom/Gas)"""
     angebotsgeber: Optional["Geschaeftspartner"] = None
-    #: Empfänger des Angebots
+    """Ersteller des Angebots"""
     angebotsnehmer: Optional["Geschaeftspartner"] = None
+    """Empfänger des Angebots"""
 
     varianten: Optional[list["Angebotsvariante"]] = None
-    """ Eine oder mehrere Varianten des Angebots mit den Angebotsteilen;
-    Ein Angebot besteht mindestens aus einer Variante."""
+    """
+    Eine oder mehrere Varianten des Angebots mit den Angebotsteilen;
+    Ein Angebot besteht mindestens aus einer Variante.
+    """
 
     anfragereferenz: Optional[str] = None
-    """	Referenz auf eine Anfrage oder Ausschreibung;
-    Kann dem Empfänger des Angebotes bei Zuordnung des Angebotes zur Anfrage bzw. Ausschreibung helfen."""
-    #: Bis zu diesem Zeitpunkt (Tag/Uhrzeit) inklusive gilt das Angebot
+    """
+    Referenz auf eine Anfrage oder Ausschreibung;
+    Kann dem Empfänger des Angebotes bei Zuordnung des Angebotes zur Anfrage bzw. Ausschreibung helfen.
+    """
     bindefrist: Optional[pydantic.AwareDatetime] = None
-    #: Person, die als Angebotsnehmer das Angebot angenommen hat
+    """Bis zu diesem Zeitpunkt (Tag/Uhrzeit) inklusive gilt das Angebot"""
     unterzeichner_angebotsnehmer: Optional["Person"] = None
-    #: Person, die als Angebotsgeber das Angebots ausgestellt hat
+    """Person, die als Angebotsnehmer das Angebot angenommen hat"""
     unterzeichner_angebotsgeber: Optional["Person"] = None
+    """Person, die als Angebotsgeber das Angebots ausgestellt hat"""

src/bo4e/bo/ausschreibung.py

@@ -37,16 +37,16 @@ class Ausschreibung(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.AUSSCHREIBUNG], Field(alias="_typ")] = Typ.AUSSCHREIBUNG
-    #: Vom Herausgeber der Ausschreibung vergebene eindeutige Nummer
     ausschreibungsnummer: Optional[str] = None
-    #: Aufzählung für die Typisierung von Ausschreibungen
+    """Vom Herausgeber der Ausschreibung vergebene eindeutige Nummer"""
     ausschreibungstyp: Optional["Ausschreibungstyp"] = None
-    #: Bezeichnungen für die Ausschreibungsphasen
+    """Aufzählung für die Typisierung von Ausschreibungen"""
     ausschreibungsstatus: Optional["Ausschreibungsstatus"] = None
-    #: Kennzeichen, ob die Ausschreibung kostenpflichtig ist
+    """Bezeichnungen für die Ausschreibungsphasen"""
     ist_kostenpflichtig: Optional[bool] = None
-    #: Gibt den Veröffentlichungszeitpunkt der Ausschreibung an
+    """Kennzeichen, ob die Ausschreibung kostenpflichtig ist"""
     veroeffentlichungszeitpunkt: Optional[pydantic.AwareDatetime] = None
+    """Gibt den Veröffentlichungszeitpunkt der Ausschreibung an"""
     ausschreibender: Optional["Geschaeftspartner"] = None
     """
     Mit diesem Objekt können Geschäftspartner übertragen werden.
@@ -62,10 +62,10 @@ class Ausschreibung(Geschaeftsobjekt):
     Diese Komponente wird zur Abbildung von Zeiträumen in Form von Dauern oder der Angabe von Start und Ende verwendet.
     Es muss daher entweder eine Dauer oder ein Zeitraum in Form von Start und Ende angegeben sein
     """
-    #: Die einzelnen Lose, aus denen sich die Ausschreibung zusammensetzt
     lose: Optional[list["Ausschreibungslos"]] = None
+    """Die einzelnen Lose, aus denen sich die Ausschreibung zusammensetzt"""
 
-    #: Aufzählung der unterstützten Ausschreibungsportale
     ausschreibungportal: Optional["Ausschreibungsportal"] = None
-    #: Internetseite, auf der die Ausschreibung veröffentlicht wurde (falls vorhanden)
+    """Aufzählung der unterstützten Ausschreibungsportale"""
     webseite: Optional[str] = None
+    """Internetseite, auf der die Ausschreibung veröffentlicht wurde (falls vorhanden)"""

src/bo4e/bo/buendelvertrag.py

@@ -41,32 +41,36 @@ class Buendelvertrag(Geschaeftsobjekt):
     typ: Annotated[Literal[Typ.BUENDELVERTRAG], Field(alias="_typ")] = Typ.BUENDELVERTRAG
 
     # pylint: disable=duplicate-code
-    #: Eine im Verwendungskontext eindeutige Nummer für den Vertrag
     vertragsnummer: Optional[str] = None
-    #: Hier ist festgelegt, um welche Art von Vertrag es sich handelt. Z.B. Netznutzungvertrag
+    """Eine im Verwendungskontext eindeutige Nummer für den Vertrag"""
     vertragsart: Optional["Vertragsart"] = None
-    #: Gibt den Status des Vertrages an
+    """Hier ist festgelegt, um welche Art von Vertrag es sich handelt. Z.B. Netznutzungvertrag"""
     vertragsstatus: Optional["Vertragsstatus"] = None
-    #: Unterscheidungsmöglichkeiten für die Sparte
+    """Gibt den Status des Vertrages an"""
     sparte: Optional["Sparte"] = None
-    #: Gibt an, wann der Vertrag beginnt (inklusiv)
+    """Unterscheidungsmöglichkeiten für die Sparte"""
     vertragsbeginn: Optional[pydantic.AwareDatetime] = None
-    #: Gibt an, wann der Vertrag (voraussichtlich) endet oder beendet wurde (exklusiv)
+    """Gibt an, wann der Vertrag beginnt (inklusiv)"""
     vertragsende: Optional[pydantic.AwareDatetime] = None
-    #: Der "erstgenannte" Vertragspartner. In der Regel der Aussteller des Vertrags.
-    #: Beispiel: "Vertrag zwischen Vertagspartner 1 ..."
+    """Gibt an, wann der Vertrag (voraussichtlich) endet oder beendet wurde (exklusiv)"""
     vertragspartner1: Optional["Geschaeftspartner"] = None
-    #: Der "zweitgenannte" Vertragspartner. In der Regel der Empfänger des Vertrags.
-    #: Beispiel "Vertrag zwischen Vertagspartner 1 und Vertragspartner 2"
+    """
+    Der "erstgenannte" Vertragspartner. In der Regel der Aussteller des Vertrags.
+    Beispiel: "Vertrag zwischen Vertagspartner 1 ..."
+    """
     vertragspartner2: Optional["Geschaeftspartner"] = None
+    """
+    Der "zweitgenannte" Vertragspartner. In der Regel der Empfänger des Vertrags.
+    Beispiel "Vertrag zwischen Vertagspartner 1 und Vertragspartner 2"
+    """
 
-    #: Die Liste mit den Einzelverträgen zu den Abnahmestellen
     einzelvertraege: Optional[list["Vertrag"]] = None
-    #: Festlegungen zu Laufzeiten und Kündigungsfristen
+    """Die Liste mit den Einzelverträgen zu den Abnahmestellen"""
     vertragskonditionen: Optional[list["Vertragskonditionen"]] = None
-    #: Unterzeichner des Vertragspartners1
+    """Festlegungen zu Laufzeiten und Kündigungsfristen"""
     unterzeichnervp1: Optional[list["Unterschrift"]] = None
-    #: Unterzeichner des Vertragspartners2
+    """Unterzeichner des Vertragspartners1"""
     unterzeichnervp2: Optional[list["Unterschrift"]] = None
-    #: Beschreibung zum Vertrag
+    """Unterzeichner des Vertragspartners2"""
     beschreibung: Optional[str] = None
+    """Beschreibung zum Vertrag"""

src/bo4e/bo/energiemenge.py

@@ -35,12 +35,12 @@ class Energiemenge(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.ENERGIEMENGE], Field(alias="_typ")] = Typ.ENERGIEMENGE
-    #: Eindeutige Nummer der Marktlokation bzw. der Messlokation, zu der die Energiemenge gehört
     lokations_id: Optional[str] = None
+    """Eindeutige Nummer der Marktlokation bzw. der Messlokation, zu der die Energiemenge gehört"""
     # todo: add validator such that only mess- or marktlokations IDs are accepted + cross check with lokationstyp
-    #: Gibt an, ob es sich um eine Markt- oder Messlokation handelt
     lokationstyp: Optional["Lokationstyp"] = None
+    """Gibt an, ob es sich um eine Markt- oder Messlokation handelt"""
 
-    #: Gibt den Verbrauch in einer Zeiteinheit an
     energieverbrauch: Optional[list["Verbrauch"]] = None
+    """Gibt den Verbrauch in einer Zeiteinheit an"""
     # there are no optional attributes

src/bo4e/bo/fremdkosten.py

@@ -36,9 +36,9 @@ class Fremdkosten(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.FREMDKOSTEN], Field(alias="_typ")] = Typ.FREMDKOSTEN
-    #: Für diesen Zeitraum wurden die Kosten ermittelt
     gueltigkeit: Optional["Zeitraum"] = None
-    #: Die Gesamtsumme über alle Kostenblöcke und -positionen
+    """Für diesen Zeitraum wurden die Kosten ermittelt"""
     summe_kosten: Optional["Betrag"] = None
-    #: In Kostenblöcken werden Kostenpositionen zusammengefasst. Beispiele: Netzkosten, Umlagen, Steuern etc
+    """Die Gesamtsumme über alle Kostenblöcke und -positionen"""
     kostenbloecke: Optional[list["Fremdkostenblock"]] = None
+    """In Kostenblöcken werden Kostenpositionen zusammengefasst. Beispiele: Netzkosten, Umlagen, Steuern etc"""

src/bo4e/bo/geraet.py

@@ -35,11 +35,11 @@ class Geraet(Geschaeftsobjekt):
 
     typ: Annotated[Literal[Typ.GERAET], Field(alias="_typ")] = Typ.GERAET
 
-    #: Die auf dem Gerät aufgedruckte Nummer, die vom MSB vergeben wird.
     geraetenummer: Optional[str] = None
-    #: Bezeichnung des Geräts
+    """Die auf dem Gerät aufgedruckte Nummer, die vom MSB vergeben wird."""
     bezeichnung: Optional[str] = None
-    #: Die übergreifende Klasse eines Geräts, beispielsweise Wandler
+    """Bezeichnung des Geräts"""
     geraeteklasse: Optional["Geraeteklasse"] = None
-    #: Der speziellere Typ eines Gerätes, beispielsweise Stromwandler
+    """Die übergreifende Klasse eines Geräts, beispielsweise Wandler"""
     geraetetyp: Optional["Geraetetyp"] = None
+    """Der speziellere Typ eines Gerätes, beispielsweise Stromwandler"""

src/bo4e/bo/geschaeftsobjekt.py

@@ -31,9 +31,10 @@ class Geschaeftsobjekt(BaseModel):  # pragma: no cover
     """
 
     # required attributes
-    version: Annotated[Optional[str], Field(alias="_version")] = (
-        __version__  #: Version der BO-Struktur aka "fachliche Versionierung"
-    )
+    version: Annotated[Optional[str], Field(alias="_version")] = __version__
+    """
+    Version der BO-Struktur aka "fachliche Versionierung"
+    """
 
     zusatz_attribute: Optional[list["ZusatzAttribut"]] = None
     # zusatz_attribute is a list of ZusatzAttribut objects which are used to store additional information
@@ -46,8 +47,8 @@ class Geschaeftsobjekt(BaseModel):  # pragma: no cover
     Z.B. könnten hier UUIDs aus einer Datenbank stehen oder URLs zu einem Backend-System.
     """
 
-    #: Hier können IDs anderer Systeme hinterlegt werden (z.B. eine SAP-GP-Nummer oder eine GUID)
     # pylint: disable=duplicate-code
+    # basic configuration for pydantic's behaviour
     model_config = ConfigDict(
         alias_generator=camelize,
         populate_by_name=True,
@@ -56,7 +57,5 @@ class Geschaeftsobjekt(BaseModel):  # pragma: no cover
         # an annotated version of Decimal, but you would have to use it everywhere in the pydantic models.
         # See this issue for more info: https://github.com/pydantic/pydantic/issues/6375
         json_encoders={Decimal: str},
+        use_attribute_docstrings=True,
     )
-    """
-    basic configuration for pydantic's behaviour
-    """

src/bo4e/bo/geschaeftspartner.py

@@ -40,19 +40,19 @@ class Geschaeftspartner(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.GESCHAEFTSPARTNER], Field(alias="_typ")] = Typ.GESCHAEFTSPARTNER
-    #: Mögliche Anrede der Person
     anrede: Optional["Anrede"] = None
+    """Mögliche Anrede der Person"""
     individuelle_anrede: Optional[str] = None
     """
     Im Falle einer nicht standardisierten Anrede kann hier eine frei definierbare Anrede vorgegeben werden.
     Beispiel: "Vereinsgemeinschaft", "Pfarrer", "Hochwürdigster Herr Abt".
     """
-    #: Möglicher Titel der Person
     titel: Optional["Titel"] = None
-    #: Vorname der Person
+    """Möglicher Titel der Person"""
     vorname: Optional[str] = None
-    #: Nachname (Familienname) der Person
+    """Vorname der Person"""
     nachname: Optional[str] = None
+    """Nachname (Familienname) der Person"""
 
     ansprechpartner: Optional[list["Person"]] = None
     organisationstyp: Optional["Organisationstyp"] = None
@@ -63,22 +63,26 @@ class Geschaeftspartner(Geschaeftsobjekt):
     """
     Name der Firma, wenn Gewerbe oder andere Organisation.
     """
-    #: Kontaktwege des Geschäftspartners
     kontaktwege: Optional[list["Kontaktweg"]] = None
-    #: Rollen, die die Geschäftspartner inne haben (z.B. Interessent, Kunde)
+    """Kontaktwege des Geschäftspartners"""
     geschaeftspartnerrollen: Optional[list["Geschaeftspartnerrolle"]] = None
-    #: Handelsregisternummer des Geschäftspartners
+    """Rollen, die die Geschäftspartner inne haben (z.B. Interessent, Kunde)"""
     handelsregisternummer: Optional[str] = None
-    #: Amtsgericht bzw Handelsregistergericht, das die Handelsregisternummer herausgegeben hat
+    """Handelsregisternummer des Geschäftspartners"""
     amtsgericht: Optional[str] = None
-    #: Die Steuer-ID des Geschäftspartners; Beispiel: "DE 813281825"
+    """Amtsgericht bzw Handelsregistergericht, das die Handelsregisternummer herausgegeben hat"""
     umsatzsteuer_id: Optional[str] = None
-    #: Die Gläubiger-ID welche im Zahlungsverkehr verwendet wird; Z.B. "DE 47116789"
+    """
+    Die Steuer-ID des Geschäftspartners; Beispiel: "DE 813281825"
+    """
     glaeubiger_id: Optional[str] = None
-    #: Internetseite des Marktpartners
+    """
+    Die Gläubiger-ID welche im Zahlungsverkehr verwendet wird; Z.B. "DE 47116789"
+    """
     website: Optional[str] = None
-    #: Adresse des Geschäftspartners
+    """Internetseite des Marktpartners"""
     adresse: Optional["Adresse"] = None
-    #: Todo: Add optional connection to marktteilnehmer as discussed in workshop
-    #: not clear what is the best solution here - circular import marktteilnehmer?
-    #: discussed in workshop on Feb 6 2024: yes we need the bidirectional option, let's figure out a solution somehow.
+    """Adresse des Geschäftspartners"""
+    # Todo: Add optional connection to marktteilnehmer as discussed in workshop
+    # not clear what is the best solution here - circular import marktteilnehmer?
+    # discussed in workshop on Feb 6 2024: yes we need the bidirectional option, let's figure out a solution somehow.

src/bo4e/bo/kosten.py

@@ -37,12 +37,12 @@ class Kosten(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.KOSTEN], Field(alias="_typ")] = Typ.KOSTEN
-    #: Klasse der Kosten, beispielsweise Fremdkosten
     kostenklasse: Optional["Kostenklasse"] = None
-    #: Für diesen Zeitraum wurden die Kosten ermittelt
+    """Klasse der Kosten, beispielsweise Fremdkosten"""
     gueltigkeit: Optional["Zeitraum"] = None
-    #: In Kostenblöcken werden Kostenpositionen zusammengefasst. Beispiele: Netzkosten, Umlagen, Steuern etc
+    """Für diesen Zeitraum wurden die Kosten ermittelt"""
     kostenbloecke: Optional[list["Kostenblock"]] = None
+    """In Kostenblöcken werden Kostenpositionen zusammengefasst. Beispiele: Netzkosten, Umlagen, Steuern etc"""
 
-    #: Die Gesamtsumme über alle Kostenblöcke und -positionen
     summe_kosten: Optional[list["Betrag"]] = None
+    """Die Gesamtsumme über alle Kostenblöcke und -positionen"""

src/bo4e/bo/lastgang.py

@@ -41,18 +41,18 @@ class Lastgang(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[Typ.LASTGANG], Field(alias="_typ")] = Typ.LASTGANG
-    #: Angabe, ob es sich um einen Gas- oder Stromlastgang handelt
     sparte: Optional["Sparte"] = None
-    #: Definition der gemessenen Größe anhand ihrer Einheit
+    """Angabe, ob es sich um einen Gas- oder Stromlastgang handelt"""
     messgroesse: Optional["Mengeneinheit"] = None
+    """Definition der gemessenen Größe anhand ihrer Einheit"""
     #:Marktlokation, zu der der Lastgang gehört
     marktlokation: Optional["Marktlokation"] = None
     #:Marktlokation, zu der der Lastgang gehört
     messlokation: Optional["Messlokation"] = None
-    #: Die im Lastgang enthaltenen Messwerte
     werte: Optional[list["Zeitreihenwert"]] = None
-    #: Versionsnummer des Lastgangs
+    """Die im Lastgang enthaltenen Messwerte"""
     version: Optional[str] = None
-    #: Die OBIS-Kennzahl für den Wert, die festlegt, welche Größe mit dem Stand gemeldet wird, z.B. '1-0:1.8.1'
+    """Versionsnummer des Lastgangs"""
     obis_kennzahl: Optional[str] = None
+    """Die OBIS-Kennzahl für den Wert, die festlegt, welche Größe mit dem Stand gemeldet wird, z.B. '1-0:1.8.1'"""
     zeit_intervall_laenge: Optional["Menge"]