Automatische Übersetzung von Rmd zu MyST markdown files

jhorzek commented 1 year ago

JupyterBook erwartet Markdown files im MyST - Style. Dieser ist hier dokumentiert: https://jupyterbook.org/en/stable/reference/cheatsheet.html. Um die Arbeit mit der RLernplattform zu vereinfachen, soll eine Funktion automatisch Rmd zu md im MyST Stil übersetzen. Aufbau der Funktion:

Suche nach Rmd Dateien im Ordner Aufgaben_rmd
Die Dateien werden nacheinander eingelesen
Es wird ein passender yaml header ergänzt
Die Settings der code-chunks werden automatisch ersetzt
Optional: Falls ein nicht erlaubtes Setting genutzt wird, wird ein Fehler ausgegeben
Die Datei wird als .md Datei im Projekt gespeichert

behnkec commented 1 year ago

@jhorzek ich habe mal einen ersten Versuch gestartet, das umzusetzen. Vielleicht könntest du mal testen, ob es bei dir auch klappt.

Das funktioniert schon:

YAML header ersetzen (im Moment mit der Konfiguration aus der Datei aufgabe_test, das lässt sich aber anpassen)
einfach R chunks (ohne Settings) zu Myst R Chunks umwandeln
das ganze als .md Datei mit gleichem Namen speichern

Das wird noch benötigt:

[x] Datei nicht in Aufgaben_rmd speichern, sondern im main directory
[x] Settings der code chunks übersetzen
[x] Fehler, falls nicht erlaubte Settings genutzt werden

jhorzek commented 1 year ago

Mega gut! Ich habe die Funktion noch etwas erweitert, damit die code-chunks auch dann übersetzt werden können, wenn dort ein Leerzeichen in { r } ist oder der code-chunk einen Namen hat (z.B. { r my_name}). Wenn ein Fall auftritt, der nicht übersetzt werden kann, wirft die Funktion einen Fehler. Könntest Du noch ein paar mehr Test-Dokumente einfügen und die Funktion mit diesen überpüfen?

Ich fände es gut, wenn wir noch eine zweite Funktion hätten, die automatisch nach .Rmd - Dateien im Ordner Aufgaben_rmd sucht. Diese werden dann automatisch mit der von Dir geschriebenen rmd2myst - Funktion übersetzt und gespeichert. Könntest Du eine solche Funktion schreiben?

jhorzek commented 1 year ago

Ich habe den Branch in main übernommen, damit wir die automatische Übersetzung mit Deiner Funktion in GitHub Actions testen können. Ich habe außerdem die Übersetzungsfunktion so erweitert, dass sie auch ein paar Tags automatisch übersetzen kann. Der Code ist nicht sonderlich schön; wenn Du willst, kannst Du gerne noch nachbessern! Du kannst auch mal schauen, ob Du noch weitere Tags einbauen kannst (hier findest Du die in myst unterstützten Tags: https://jupyterbook.org/en/stable/reference/cheatsheet.html#tags). Vielleicht hast Du eine Idee, wie wir mit eval = FALSE umgehen; hier gebe ich aktuell einfach einen Fehler aus.

Ich habe leider keine Möglichkeit gefunden, <details> zum Laufen zu bringen. Könntest Du noch mal schauen, ob Du einen Weg findest? Aktuell erlaube ich folgendes:

<details> - Blöcke, in denen nur Text steht (das funktionert)
<details> - Blöcke, in denen nur ein Code-Block ist (kann automatisch übersetzt werden)

Es wäre gut, wenn wir auch eine Mischung beider Blöcke anbieten könnten, um code und Erklärungen einzufügen.

[ ] weitere test-Dokumente hinzufügen
[ ] weitere Tags automatisch übersetzen
[ ] bessere Möglichkeit zum Umgang mit <details> finden
[ ] automatisch prüfen, ob die Überschriften auf dem richtigen Level sind. Die erste Überschrift muss auf Level 1 sein, alle anderen auf einem niedrigeren Level
[x] wollen wir automatisch Themen in die _toc.yml - Datei übernehmen? Wir könnten das ähnlich wie bei Bookdown machen: Die Aufgaben in Augaben_rmd müssen durchnummiert sein (0-R, 1-Datenverarbeitung, ...) und werden dann automatisch in dieser Reihenfolge in _toc.yml übernommen. Das könnte es einfacher machen, neue Aufgaben hinzuzufügen.

jhorzek commented 1 year ago

Es scheint wichtig zu sein, dass der yaml header bei .md Dateien ganz oben ist; es darf keine leere Zeile vor dem yaml header kommen

behnkec commented 1 year ago

Du hast einen Download Link hinzugefügt, dass ist ja mega cool!

Für eval=false könnte man statt einen Tag zu benutzen, die erste Zeile des Code Blocks von {code-cell} r zur umschreiben, dann sollten sie nicht ausgeführt werden

behnkec commented 1 year ago

Ich finde es eine gute Idee, automatisch Themen in _toc.yml zu übernehmen. Ich würde auch vorschlagen, dass wir die gleiche Einteilung in Chapters machen, wie bei der RLernplattform

jhorzek commented 1 year ago

Du hast einen Download Link hinzugefügt, dass ist ja mega cool!

Für eval=false könnte man statt einen Tag zu benutzen, die erste Zeile des Code Blocks von {code-cell} r zur umschreiben, dann sollten sie nicht ausgeführt werden

Finde ich gut! Könntest Du das hinzufügen?

behnkec commented 1 year ago

* [ ]  automatisch prüfen, ob die Überschriften auf dem richtigen Level sind. Die erste Überschrift muss auf Level 2 sein, alle anderen auf einem niedrigeren Level

Warum muss die erste Überschrift auf Level 2 sein? Wäre es nicht sinnvoll die erste auf Level 1 zu haben (das findet sich ja dann auch im toc wieder). Sonst ist man schnell bei 4 oder 5 #'s.

jhorzek commented 1 year ago

* [ ]  automatisch prüfen, ob die Überschriften auf dem richtigen Level sind. Die erste Überschrift muss auf Level 2 sein, alle anderen auf einem niedrigeren Level
Warum muss die erste Überschrift auf Level 2 sein? Wäre es nicht sinnvoll die erste auf Level 1 zu haben (das findet sich ja dann auch im toc wieder). Sonst ist man schnell bei 4 oder 5 #'s.

Ich hatte wahrscheinlich einfach das Problem, dass bei mir die Überschriften etwas drunter und drüber waren, aber bei mir hatte es mit Level 1 Überschriften nicht richtig funktioniert. Aber probier das gerne noch mal aus; am Ende ist wahrscheinlich nur wichtig, dass alle Dokumente auf dem selben Level anfangen.

behnkec commented 1 year ago

Ok!

jhorzek commented 1 year ago

eval = FALSE kombiniert mit <details> funktioniert nicht: https://methods-berlin.github.io/RTraining/Aufgaben_hinzufuegen.html#details-code-block-mit-eval-false

jhorzek commented 1 year ago

Ich finde leider keine Möglichkeit, eval=FALSE mit details zu verbinden. Das wäre praktisch, wenn man Code optional anzeigen möchte, der aber nicht ausgeführt werden soll.

Folgendes habe ich ausprobiert:

normalen code-Block in details-Block einsetzen
:tags: [hide-cell] hinzufügen

Wenn Du noch eine Idee hast @behnkec , probiere sie gerne aus.

behnkec commented 1 year ago

Wenn Du noch eine Idee hast @behnkec , probiere sie gerne aus.

Das einzige, was bei mir bisher funktioniert hat, ist mit html Code selbst einen Code Block zu erstellen. Wie hier: https://github.com/Methods-Berlin/RTraining/commit/86be4fe8311c29e5443599dcea54ca948b04e3b7

behnkec commented 1 year ago

@jhorzek wie wollen wir hier weiter vorgehen? Ich finde es gerade noch schwierig einzuschätzen, wie wir die Waage halten zwischen genügend Optionen zur Gestaltung ermöglichen aber auch die Funktion nicht zu kleinteilig zu gestalten.

jhorzek commented 1 year ago

Ich würde gerne noch eval=FALSE mit details verbinden, da das für Antworten und Beispiele recht interessant sein kann. Könntest Du Deinen Ansatz mit html code-blocks versuchen einzubauen? Bei allem anderen bin ich auch offen für eine pragmatische Herangehensweise: Wenn wir merken, dass ein wichtiges Element fehlt, fügen wir es noch hinzu.

Methods-Berlin / RTraining

Automatische Übersetzung von Rmd zu MyST markdown files #5