search

claeis / ili2db

interlis import/export to relational databases
30 stars 30 forks source link

Dokumentation docs/ili2db.rst wird nicht gerendert nach HTML #533

Open beistehen opened 8 months ago

beistehen commented 8 months ago

Dies scheint ein Github Problem zu sein:

https://github.com/orgs/community/discussions/86715

Die Lösung dafür ist noch nicht bekannt. Ich wollte dies hier mal deponieren, falls sich noch andere Leute fragen, weshalb die Doku im Rohformat daher kommt. grafik

vvmruder commented 7 months ago

Es scheint, dass GitHub neu diese Lib nutzt um zu prüfen ob es die RST rendern kann: https://pypi.org/project/rstcheck/

Falls der Test fehlschlägt wird nicht gerendert. Ich habe es nocht nicht gegen die Docs laufen lassen.

vvmruder commented 7 months ago

Nebenbei bemerkt fand ich die Doku nie so wirklich gut zu lesen. Was spricht dagegen weiterhin das RST zu pflegen und aus dem RST automatisch ein HTML wie dieses hier zu generieren (github actions): ili2db.zip

webrian commented 7 months ago

Ich habe in einer Fork mal eine entsprechende GitHub action geschrieben, welche mit docutils den RestructuredText nach html rendert und auf GitHub pages publiziert: https://webrian.github.io/ili2db/ili2db.html

edigonzales commented 6 months ago

Ich habe es mit Quarto https://quarto.org/ ausprobiert. Damit könnte es im Extremfall einfaches Markdown bleiben. Das Teil-Resultat: https://edigonzales.github.io/ili2db/ Mit Quarto wäre der Ausbau in eine Webseite auch einfach möglich, cc @olivergrimm @claeis @beistehen: Wir hatten doch am letzten ilitools-Treffen über ne Webseite diskutiert?

Grundsätzlich gefiele mir eine Lösung, die kein Prozessing benötigt. Hat aber alles seine Grenzen. Die Tabellen sind m.E. das Problem, das man lösen muss. Ich habe das Gefühl, dass man hier in einer Nachführungshölle ist. Darum habe ich noch ne Variante mit Subkapitel pro Option. Vorteil hier, dass man auf die Option verlinken kann.

Wir müssen relativ zügig hier weiterkommen, dass ist kein Zustand, dass es a) lange geht bist die rst-Seite überhaupt angezeigt wird und b) nur noch im Quellcode-Modus funktioniert. Die Anleitung war bei uns sehr beliebt, so ist sie halt faktisch nicht mehr brauchbar und schlecht für das "INTERLIS-Image".

edigonzales commented 6 months ago

Für die Doku-Interessierten anbei ein PDF mittels dem Quarto-Typst-Backend, also ohne Umweg über PdfLatex. Ich habe überhaupt nichts konfiguriert. ili2db.pdf

beistehen commented 6 months ago

Wir müssen relativ zügig hier weiterkommen, dass ist kein Zustand, dass es a) lange geht bist die rst-Seite überhaupt angezeigt wird und b) nur noch im Quellcode-Modus funktioniert. Die Anleitung war bei uns sehr beliebt, so ist sie halt faktisch nicht mehr brauchbar und schlecht für das "INTERLIS-Image".

Offenbar wird das Problem mit den .rst-Dateien seitens github nicht gelöst. In einem ersten Schritt sollte man deshalb die Dokumentation meiner Ansicht nach in .md umbauen. @claeis @olivergrimm Seid ihr einverstanden oder gibt es vorbehalte? Ich könnte das sonst in Angriff nehmen.

claeis commented 6 months ago

Em, also es gibt im build.gradle ja einen Task der das build/docs/ili2db.html aus dem .rst erzeugt. Und das wird in jede ZIP-Datei eingebunden (so hat man eigentlich immer, auch bei SNAPSHOT-Versionen, das passende html-Doku bem jeweiligen Binary). Es braucht also m.E. keine Hau-Ruck-Umformatierungs-Aktivitäten.

edigonzales commented 5 months ago

Was ist mit https://docs.interlis.ch/ ?