Added diagram for available charging power calculation

[TheNinth7]

Added a diagram to the manipulation options section of the evcc.yaml page, explaining how the different paramters and inputs are used in the calculation of available charging power.

[TheNinth7]

Closed temporarily, to await review/clarification in the discussion evcc-io/evcc#10763.

[premultiply]

You could even set it into "draft" state.

[TheNinth7]

You could even set it into "draft" state.

Thanks, did that.

[TheNinth7]

Complete the rework now. Diagrams are now converted to drawio, and I expanded the explanation of the solar mode and put it into a new page in the guides section.

Any feedback on the new content/structure/approach is appreciated!

[TheNinth7]

I am afraid I need some help here.

So it seems some links to the newly created page do not work. I basically created a new file docs/i18n/en/docusaurus-plugin-content-docs/current/guides/solar-mode-innards.md and tried to link it with relative paths in other md/mdx files, for example: "solar-mode-innards" or "./solar-mode-innards" in other files in the guide directory. For example in index.md, it is exactly the same syntax used for linking the other guides there. The only difference seems to be that I used ".md" and the other guides are ".mdx", could that be the problem?

Anything else that I could be doing wrong?

Is there a way I can run this checks myself before submitting the PR?

Here is the error from the build process:

Error:  Unable to build website for locale en.
Error:  Error: Docusaurus found broken links!

Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
[INFO] Docusaurus version: 2.4.1
Node version: v18.18.2
Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken links found:

- On source page path = /en/docs/guides/:
   -> linking to solar-mode-innards (resolved as: /en/docs/guides/solar-mode-innards)

- On source page path = /en/docs/guides/charging:
   -> linking to ./solar-mode-innards (resolved as: /en/docs/guides/solar-mode-innards)

- On source page path = /en/docs/guides/setup:
   -> linking to ./solar-mode-innards (resolved as: /en/docs/guides/solar-mode-innards)

- On source page path = /en/docs/reference/configuration/:
   -> linking to ../../guides/solar-mode-innards (resolved as: /en/docs/guides/solar-mode-innards)

- On source page path = /en/docs/reference/configuration/loadpoints:
   -> linking to ../../guides/solar-mode-innards#calculation-of-available-charging-power (resolved as: /en/docs/guides/solar-mode-innards)
   -> linking to ../../guides/solar-mode-innards#timing-interval-and-delays (resolved as: /en/docs/guides/solar-mode-innards)

- On source page path = /en/docs/reference/configuration/site:
   -> linking to ../../guides/solar-mode-innards#calculation-of-available-charging-power (resolved as: /en/docs/guides/solar-mode-innards)

    at throwError (/home/runner/work/docs/docs/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at handleBrokenLinks (/home/runner/work/docs/docs/node_modules/@docusaurus/core/lib/server/brokenLinks.js:153:47)
    at async buildLocale (/home/runner/work/docs/docs/node_modules/@docusaurus/core/lib/commands/build.js:186:5)
    at async tryToBuildLocale (/home/runner/work/docs/docs/node_modules/@docusaurus/core/lib/commands/build.js:41:20)
    at async mapAsyncSequential (/home/runner/work/docs/docs/node_modules/@docusaurus/utils/lib/jsUtils.js:34:24)
    at async Command.build (/home/runner/work/docs/docs/node_modules/@docusaurus/core/lib/commands/build.js:76:21)
Error: Process completed with exit code 1.

[naltatis]

Hi @TheNinth7, großen Respekt für das Zusammentragen bzw. "Reverse-Engineeren", das du gemacht hast. Ich hab, deine Blog-Artikel gelesen und werd die auch gleich mal auf der Startseite verlinken.

Ich glaub’ auch, dass es wertvoll ist, dieses Level an Content für "Advanced Nutzer" in der Doku zu haben. Also etwas für Menschen, die genau wissen wollen, wie das funktioniert, aber nicht den Schritt in den Source-Code und eigenes Debugging gehen wollen.

Ich hab allerdings auch einige Bedenken, wenn wir so etwas in die Doku aufnehmen:

1. Aktualität und Pflege: Aktuell ist es schon eine Herausforderung, die Doku aus Nutzersicht immer aktuell zu halten. Also welche Parameter es gibt und welche praktischen Nutzen sie haben. Wenn wir auf das Level der Steuerlogik und Implementierung runtergehen muss der Inhalt noch deutlich häufiger upgedatet werden. Aktuell bauen wir bspw. komplett um, wie Ladelimits im Zusammenspiel mit dem Planer funktionieren. So etwas müsste dann natürlich auch in der "Advanced Doku" nachgepflegt werden.
2. Diagramme: Ich finde Grafiken zur Veranschaulichung gut. Die sind allerdings deutlich schwerer auf Stand zu halten als Textinhalte. Suchen/Ersetzen ist nicht wirklich möglich. Übersetzung ist schwierig und ich brauch idR. ein separates Grafikprogramm. Wir haben an einer Stelle bereits ein Diagramm mit Marmaid in der Doku. Das hat den Vorteil, dass das Diagramm direkt im Markdown hinterlegt werden kann. Schränkt aber natürlich auch in der Gestaltung etwas ein (was nicht immer schlecht sein muss, KISS und so). Hier auch lieber mehrere kleine Diagramme, die einzelne Aspekte erklären als eine große, gut strukturierte, aber händisch gestaltete Infografik. Ersteres bekommen wir halt besser auf Stand gehalten und angepasst.
3. English only?: Ich glaub bei dieser Detailtiefe an Inhalt wäre es total ok den nur auf Englisch zu pflegen (weniger Pflege / siehe 1.). Hier steht uns Docosaurus im Weg, weil wir (aus historischen Gründen) Deutsch als Mastersprache haben. Aber das hält uns natürlich nicht davon ab, den englischen Inhalt einfach direkt im deutschen Zweig zu pflegen und dann keine Übersetzung dafür anzulegen (Fallback Master-Sprache). Vielleicht muss man dann noch irgendwas machen, damit die Bots (interne Suche und Google, ...) hier die richtige Sprachauszeichnung bekommen, aber das sind Details, die ich mir dann noch mal anschauen kann.

Zur Struktur: Ich würde vorschlagen, einen neuen Menüpunkt auf der Hauptebene hinzuzufügen, unter dem wir diesen Inhalt mit höherem Detaillevel ansiedeln. Vorschlag:

...
Tips & FAQ
Devices
Reference
Inner Workings <<<
Sponsorship

Ich hab das hier mal Inner Workings genannt. Gerne auch Alternativvorschläge. Muss halt klarmachen, dass es hier nicht um Einrichtung und Grundverständnis geht, sondern um weiterführende Details für technisch interessierte Nutzer.

Unterhalb dieses Menüpunkts würde ich am liebsten kleine Seiten haben, die sich mit einem Aspekt auseinandersetzen. Das ist nicht immer einfach, weil das natürlich alles zusammenspielt, aber hilft mMn. beim Strukturieren und Erfassen.

Inner Workings
- Multiple Loadpoints
- Solar mode
- Timeouts
- Planner
- ...

Diese Seiten könnten/sollten wir dann aus der Nutzer-Doku immer als "weiterführende Ressource" verlinken, wo es passt.

Das ist jetzt einiges an Änderung und es tut mir auch Leid, dass ich erst so spät in diese Diskussion einsteige. Hoffe aber, dass du die Punkte bzw. meine Bedenken zum jetzigen Vorschlag verstehst. Kannst du dir die skizzierte Form vorstellen? Zu den Grafiken: die Jetzigen wird man nicht 1:1 in Marmaid überführen können. Das Tool ist aber relativ mächtig, unterstützt einige unterschiedliche Diagrammtypen und hat einen Live-Editor zum Ausprobieren. Kannst du dir vorstellen, das zur Illustration zu verwenden?

[TheNinth7]

Das ist jetzt einiges an Änderung und es tut mir auch Leid, dass ich erst so spät in diese Diskussion einsteige. Hoffe aber, dass du die Punkte bzw. meine Bedenken zum jetzigen Vorschlag verstehst. Kannst du dir die skizzierte Form vorstellen?

Ja, kann deine Bedenken nachvollziehen!

Das Thema ist größer geworden anfänglich erwartet, ich habe naiv mit einem Diagramm angefangen, das wurde dann immer größer und es kamen weitere Aspekte dazu die nicht in das eine Diagram gepasst haben. ;-)

Die Struktur wie du sie vorschlägst macht auf jeden Fall Sinn, das kann ich so umbauen. Bei den Diagrammen bin ich mir noch unsicher, die sind sicher das größte "Problem". Hab mir mal die Mermaid-Doku mit den verschiedenen Diagrammtypen angeschaut und bin mir noch nicht sicher wie man die verschiedenen Sachverhalte damit eingänglich darstellen kann. Vielleicht muss ich aber nur ein wenig umdenken, ich schau mir das mal näher an und melde mich dann wieder.

[naltatis]

Super! Bist du eigentlich im Slack? Ping mich da sonst bei Fragen auch gerne direkt an.

Hab mir mal die Mermaid-Doku mit den verschiedenen Diagrammtypen angeschaut und bin mir noch nicht sicher wie man die verschiedenen Sachverhalte damit eingänglich darstellen kann.

Ja, ich verstehe was du meinst. Vmtl. muss man die Punkte, die in den aktuelle Grafiken erklärt werden noch weiter runterbrechen, aufteilen bzw. auf den Kern reduzieren damit das in diesem Format gut funktioniert.

[TheNinth7]

Schönen Nachmittag! Hab jetzt gerade einen neuen Entwurf committed, mit den mit @naltatis besprochenen Kommentaren.

• Neuer Menüpunkt "Inner-workings", mit einzelnen Kapiteln zu den verschiedenen Themen
• Aufteilung des Monster-Diagrams auf zwei Kapitel und mehrere Grafiken
• Die Diagramme sind zwecks Wartbarkeit direkt über ein Plugin in Docusaurus eingebunden

Freue mich über Kommentare!

[naltatis]

Super. Ich schau mir das bei Gelegenheit in Ruhe an.