Update and enhance documentation #100

Move documentation from readme into sphinx
change theme from alabaster to sphinxawsome-theme
version bump sphinx to 8.1.2
split into technical and user documentation
- restructure docs/ directories
- update sphinx refs in user documentation
extend technical documentation with contributing page
create seed for more technical documentation (architecture, deployment, testing)

Ich habe einige Links aus Deiner @christian.merten ursprünglichen Nutzer Doku umbenannt, die sollten alle wieder funktionieren.

- Move documentation from readme into sphinx - change theme from alabaster to sphinxawsome-theme - version bump sphinx to 8.1.2 - split into technical and user documentation - restructure docs/ directories - update sphinx refs in user documentation - extend technical documentation with contributing page - create seed for more technical documentation (architecture, deployment, testing) Ich habe einige Links aus Deiner @christian.merten ursprünglichen Nutzer Doku umbenannt, die sollten alle wieder funktionieren.

Ich bekomme

30.54 ERROR: No matching distribution found for Sphinx==8.1.3

Hast du die geupdatede requirements.txt in einem cleanen docker build getestet?

Ich bekomme ``` 30.54 ERROR: No matching distribution found for Sphinx==8.1.3 ``` Hast du die geupdatede `requirements.txt` in einem cleanen docker build getestet?

Das hatte ich tatsächlich nicht getestet. Bei mir hat es im docker auch nicht geklappt. Das liegt an der python Version. Lokal habe ich 3.11 und der docker container nutzt 3.9.

Ich habe jetzt mal lokal das docker image auf python:3.11-bullseye gesetzt, dann klappt der build problemlos.

Ich bin mir aber nicht sicher, ob ich das allgemein machen kann oder das dann wo anders Probleme verursacht.

Das hatte ich tatsächlich nicht getestet. Bei mir hat es im docker auch nicht geklappt. Das liegt an der python Version. Lokal habe ich 3.11 und der docker container nutzt 3.9. Ich habe jetzt mal lokal das docker image auf `python:3.11-bullseye` gesetzt, dann klappt der build problemlos. Ich bin mir aber nicht sicher, ob ich das allgemein machen kann oder das dann wo anders Probleme verursacht.

Hmm, mit python version auf 3.11 hochsetzen wäre ich vorsichtig, da müsste man schon erstmal ausgiebig testen (und leider ist die test coverage zur Zeit so niedrig, dass ich da nicht viel Sicherheit ziehen würde). Ist die höhere sphinx Version zwingend notwendig?

Ich hatte die hochgesetzt, weil ich zwischendurch über ein Feature gestolpert bin, dass es erst ab 8.1 gab.
Jetzt weiß ich aber leider nicht mehr welches das war... Ich guck nochmal.

Ich hatte die hochgesetzt, weil ich zwischendurch über ein Feature gestolpert bin, dass es erst ab 8.1 gab. Jetzt weiß ich aber leider nicht mehr welches das war... Ich guck nochmal.

Lokal scheint es mir auch mit sphinx 7.4.7 ohne Einschränkungen zu klappen.

Im docker kann ich es gerade leider nicht testen, weil das development image die doku nicht served (oder?) und ich für das production image keine funktionierende .env Datei habe.

Aber es wird auf jeden Fall mit dieser Version in beiden images erfolgreich gebaut und der html code generiert.

Lokal scheint es mir auch mit sphinx 7.4.7 ohne Einschränkungen zu klappen. Im docker kann ich es gerade leider nicht testen, weil das development image die doku nicht served (oder?) und ich für das production image keine funktionierende .env Datei habe. Aber es wird auf jeden Fall mit dieser Version in beiden images erfolgreich gebaut und der html code generiert.

Top, kannst du den PR updaten? Dann teste ich es.

Du kannst die html Dateien, die im development image generiert werden, lokal im Browser öffnen (also direct die Dateien unter docs/build/).

Top, kannst du den PR updaten? Dann teste ich es. Du kannst die html Dateien, die im development image generiert werden, lokal im Browser öffnen (also direct die Dateien unter `docs/build/`).

Also die vom development build generierte Doku in docs/build/ sieht vollständig und korrekt aus.

Sphinx version habe ich wieder gedowngraded.

Also die vom development build generierte Doku in `docs/build/` sieht vollständig und korrekt aus. Sphinx version habe ich wieder gedowngraded.

Vielen Dank!

Was ich noch nicht ganz verstehe: Wieso der _static folder? Das sieht so automatisch generiert aus. Vielleicht einfach static?

Vielen Dank! Was ich noch nicht ganz verstehe: Wieso der `_static` folder? Das sieht so automatisch generiert aus. Vielleicht einfach `static`?

_static ist der default von sphinx selber: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path

Das ist aber eigentlich egal, wir können das selber festlegen.

Es setzt sich wahrscheinlich besser ab, als die restlichen Ordner, die nur Inhalt haben und ohne führenden _ geschrieben werden. Der Templates Ordner wird teilweise auch mit _templates geschrieben. Wobei im der Doku wird er mit .templates vorgeschlagen.

`_static` ist der default von sphinx selber: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path Das ist aber eigentlich egal, wir können das selber festlegen. Es setzt sich wahrscheinlich besser ab, als die restlichen Ordner, die nur Inhalt haben und ohne führenden `_` geschrieben werden. Der Templates Ordner wird teilweise auch mit `_templates` geschrieben. Wobei im der [Doku](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-templates_path) wird er mit `.templates` vorgeschlagen.

Danke!

 @ -10,3 +14,2 @@
 copyright = '2024, Christian Merten'
 author = 'Christian Merten'
 release = '2.0'
 author = 'Christian Merten'

 @ -11,2 +14,3 @@
 author = 'Christian Merten'
 release = '2.0'
 author = 'Christian Merten'
 copyright = f'%Y, {author}'

 @ -0,0 +36,4 @@
 Workflow
 --------
 - request a gitea account with Christian

Labels Milestones

Update and enhance documentation #100

Reviewers