Documentation: Refactoring of plugins.md

[rhuss]

Hier mein erster Wurf für eine Restrukturierung von plugins.md. Dabei liegt der Fokus auf der Kapitelstruktur, es sind noch einige Gaps offen:

• Beispiele
• Tabellen mit allen Werten
• Englische Version

Out-of-scope in diesem PR:

• Beschreibung der einzelnen Plugins
• Detailierte Beschreibung von Pipelines

Beim Review koennt ihr gerne direkt korrigieren und auf den Branch pushen, er ist offen für Maintainers (vielleicht bei groesseren Aenderung noch einen Review Kommentar).

Random Opinion following ..., nicht wichtig :-)

Darueberhinaus habe ich noch ein paar kleine Anmerkungen (sorry, ich kann nicht anders :-), die aber für den PR nicht relevant sind:

• "Plugin" ist eine etwas unglueckliche Bezeichnung, das sie in vielen anderen Faellen, externen code und Konventionen bezeichnen, die ausserhalb des Kernprojekts leben und vorgegebene APIs implementieren. Im Falle von evcc ist aber die Liste der Plugins fix und koennen nicht selbst ergaenzt werden. Z.b. muesste man für eine Resol VBus Integrationen den core-code erweitern. In meinen Augen handelt es sich vielmehr um Integrationen, bei der externe Sources (oder Producer) und Sinks (oder Consumer) eingebunden werden, so wie sie z.b. in dem klassischen EAI Patterns Buch beschrieben sind. Mir ist klar das im Kontext von evcc "Integrationen" anders interpretiert wird (i.e. wie man evcc in andere Systeme integrieren kann, also mehr eine "API" Beschreibung), daher sollten man es auch so lassen. Ich will hier keine Diskussion starten, sondern mein innerer Spiesser wollte das einfach loswerden :-P und evtl. hilft das in Diskussionen um Missverstaendnisse zu vermeiden.

• Das "combined status" plugin passt in meinen Augen nicht wirklich in die Liste, da es nicht für alle Geraete genutzt werden kann (für meter macht das keinen Sinn, oder ?). Vielmehr wuerde ich es als Eigenschaft von vehicle sehen, bei denen Plugins genutzt werden koenne. Your mileage may vary.

[rhuss]

In dem PR verwende ich ds one sentence per line pattern, was es bei PR request reviews (und bei aenderungs vorschlaegen) deutlich einfacher macht. Für das Rendern macht es keinen Unterschied.

[naltatis]

In dem PR verwende ich ds one sentence per line pattern, was es bei PR request reviews (und bei aenderungs vorschlaegen) deutlich einfacher macht. Für das Rendern macht es keinen Unterschied.

Das ist gut. Das machen wir auch so.

[rhuss]

@naltatis gibt es eine Moeglichkeit, labels in der Dokumentation darzustellen ? Ich wuerde gerne zwei labels fur lesen und schreiben jeweils bei den Plugins anzeigen (anstelle von textuell (lesen / schreiben), was nicht sehr auffaellt)

[naltatis]

Ich bin den aktuellen Stand gestern einmal durchgegangen und hab dabei ein paar sprachliche Dinge mit angepasst. Die Struktur und der Erklärungslevel gefällt mir total gut. Willst du das Umhängen /docs/[reference > devices]/plugins in diesem PR gleich mit machen? Wäre für mich dann der unterste Punkt im "Geräte" Abschnitt.

Zum "Plugin" Namen: Ich verstehe die Argumentation. Das ist nur aktuell schon an so vielen Stellen in Code und Sprachgebrauch, dass das schwer zu ändern ist ohne unnötige Verwirrung zu erzeugen.

[naltatis]

@rhuss Für die Darstellung könntest du kbd oder mark Tags verwenden. Styling dafür bringt Docosaurus bereits mit. Standard Markdownsyntax gibts dafür nicht. Via Plugins ginge da was. Aber HTML Tags schreiben ist aktuell auch erlaubt.

... mit Endgeräten spricht (<kbd>lesen</kbd>/<kbd>schreiben</kbd>).
... von Daten genutzt werden <mark>(lesen)</mark>.

Optisch finde ich den kbd Style passender, weil der abgeschlossener wirkt. Semantisch passen beide nicht wirklich. Aber lass uns doch mit kbd starten.

[rhuss]

@naltatis ich hab mal meine verstaubten CSS Kenntnisse ausgegraben und eine simple React Komponente Tag.js eingebaut, um die Labels zu rendern. Die Farbgebung & Spacing kann man gerne noch anpassen, verlasse mich da aber auf die Experten ;-)

[naltatis]

Hab das etwas angepasst und das vorhanden Farbschema verwendet.

[rhuss]

Ich habe ein die Beispiele zu meter, charger und vehicle eingefuegt. Dabei habe ich mich an den Templates orientiert, kann aber nicht sagen ob meine Beispiele korrekt umgesetzt sind (oder etwas mandatory parameter fehlen), bzw. ob sie ueberhaupt Sinn machen. Es waere toll wenn ihr darueber schauen koenntet und ggfs. durch sinnvollere Beispiele ersetzt.

Als naechstes werde ich versuchen, die Tabellen sinnvoll zu ergaenzen. Da braeuchte ich spaeter dann ebenfalls die Hilfe von euch SMEs :)

[rhuss]

Willst du das Umhängen /docs/[reference > devices]/plugins in diesem PR gleich mit machen? Wäre für mich dann der unterste Punkt im "Geräte" Abschnitt.

Das wuerde ich dann am Ende machen wenn wir den Inhalt soweit festgezurrt haben.

[rhuss]

@naltatis Hast Du eine Idee, wie ich die Platzhalter (<...>) hervorheben kann ? Ich habs mit Prism plugins probiert, aber React/Docsaurus-Fu ist nicht gut genug. Idealerweise waeren die Platzhale in kursiv + bold.

Ist aber nicht dringend, man kann sicher auch ohne leben. Nur falls Du zufaellig was weisst.

Testweise habe ich line-highlight Prism plugin enabled, aber so toll ist das hier auch nicht (sollte man wohl auch mit magic comments)

[naltatis]

Line-Highlights mit Magic Comments sollten ja ohne Konfigurationsänderung schön möglich sein:

tariffs:
  currency: EUR # (default EUR)
  grid:
    // highlight-start
    type: fixed
    // highlight-end
    price: 0.294 # EUR/kWh

Aber du möchtest nur die Teilwörter, keine Zeilen richtig? Da bin ich auch überfragt.

[rhuss]

Ja, genau. Ich wollte die Platzhalter attr1 bzw attr2 hervorheben.
Aber kein Problem, das ist nur Nebensache. Inhalt ist wichtiger ;-)

Danke fuers Feedback.