Überarbeitete REDAXO-Addon-Hilfe auf Basis der README.md

[alxndr-w]

zusammengefasst aus: #716 und yakamara/redaxo_yrewrite#225

In diesem Issue benötige ich Feedback, ob meine Lösung grundsätzlich auch für den Core übernommen werden kann und was dazu noch fehlt.

Vorschlag

• Wenn es keine umfangreiche Doku gibt, könnte man immer auf die README.md zurückgreifen
• Dieser Reiter befindet sich immer rechts
• Die help.php könnte ebenfalls immer die README.md geparst ausgeben.

Vorteile

• Die README.md wird auch in Github-Repos immer richtig angezeigt. Nutzer können so mehr über das Addon erfahren, noch bevor sie es installieren.
• Addon-Entwickler und die Community hätten eine Vorgabe, wie sie Hilfe/Dokus einfach schreiben können
• Die Lösung bleibt kompatibel zur bisherigen help.php bei der Addon-Liste

Es gibt hierzu eine prototypische Umsetzung, die bspw. auch Addon-übergreifend funktionieren würde. Dazu müssten sich Addon-Entwickler an gewisse Standards bei der README.md und mehrsprachigen Seiten halten:

Beispiel

yakamara/redaxo_yrewrite#225

Features

• help.php leitet direkt auf die Doku weiter
• Automatisches parsen der README.md
  • Navigation
  • Sprunganker
  • markiert aktives Kapitel
• Mehrsprachig: Lädt ggf. /docs/README.xx_xx.md, falls die Backend-Sprache des Nutzers abweicht
• Bearbeiten-Link führt direkt zur Editieransicht in der Github-Seite (neue package.yml Property)
• Prototyp für eine generische Doku-Darstellung
• Kann mit Bildern umgehen (commit folgt)
• Kein zusätzliches CSS - basiert nur auf Bootstrap

Todo

• Layout in Fragmente auslagern
• Credits und Autor analog zur Addon-Hilfe-Seiten der Addon-Übersicht ausgeben

Screenshot

aus dem Original-Issue #716 - ping:
@gharlan @phoebusryan @tbaddade @staabm @polarpixel

[staabm]

Wenn es keine umfangreiche Doku gibt, könnte man immer auf die README.md zurückgreifen

wie erkennt man eine "umfangreiche Doku"?

Die help.php könnte ebenfalls immer die README.md geparst ausgeben.

das ist bereits der Fall, siehe

redaxo/redaxo/src/core/pages/packages.php

Lines 22 to 35 in 25e573f

	if (is_readable($package->getPath('help.php'))) {
	if (!$package->isAvailable() && is_readable($package->getPath('lang'))) {
	rex_i18n::addDirectory($package->getPath('lang'));
	}
	ob_start();
	$package->includeFile('help.php');
	$content .= ob_get_clean();
	} elseif (is_readable($package->getPath('README.md'))) {
	$fragment = new rex_fragment();
	$fragment->setVar('content', rex_markdown::factory()->parse(rex_file::get($package->getPath('README.md'))), false);
	$content .= $fragment->parse('core/page/docs.php');
	} else {
	$content .= rex_view::info(rex_i18n::msg('package_no_help_file'));
	}

wenn es keine help.inc.php gibt, aber eine README, wird diese als Hilfeseite ausgegeben.

Dazu müssten sich Addon-Entwickler an gewisse Standards bei der README.md und mehrsprachigen Seiten halten:

"einen standard für README" unterstützt der core bereits, da diese wie in github bereits integriert ist (in teilen zumindest). was meinst du mit "standards.. bei mehrsprachigen seiten"?

Beispiel

ist das was man auf dem Screenshot sieht ein "hilfe-addon" oder eine neue "redaxo core page"?

Automatisches parsen der README.md
Navigation
Sprunganker
markiert aktives Kapitel

volle zustimmung 👍 . hier kann man sicherlich noch bissl was besser machen, als wir heute tun... aktuell rendern wir nur markdown 1:1 - soweit ich mich erinnere.

Mehrsprachig: Lädt ggf. /docs/README.xx_xx.md, falls die Backend-Sprache des Nutzers abweicht

das kann github auch, soweit ich weiß. daher 👍

Bearbeiten-Link führt direkt zur Editieransicht in der Github-Seite (neue package.yml Property)

das macht sinn. hier könnte man überlegen ob man hier das ganze nur haben will für den entwickler des addons selbst oder ob das ein "crowd source" gedanken ist (ähnlich wie in der neuen tricks seite), sodass jeder "aufgefordert wird" änderungen/verbesserungen beizusteuern.

Prototyp für eine generische Doku-Darstellung

was ist damit gemeint?

Kann mit Bildern umgehen (commit folgt)

das ist denke ich ein wichtiger punkt, da man schauen muss wie/wo man die bilder (bzw. generell externe resourcen ablegt). falls die bilder irgendwo online liegen würden: ist die readme dann auch für installationen im Intranet ohne www zugang "lesbar"?

Kein zusätzliches CSS - basiert nur auf Bootstrap

finde ich wichtig. im besten falle können die "doku redakteure" nur inhalte pflegen (auch kein html o.ä.) und das system gibt die volle darstellung vor.

Credits und Autor analog zur Addon-Hilfe-Seiten der Addon-Übersicht ausgeben

wenn die inhalte auf github liegen, könnte man hier "live" die autoren aus den repositries abfragen (ähnlich wie in der neuen tricks seite)

---

generell finde ich super dass du hier in diesem bereich was bewegen willst. allgemein denke ich dass man im besten fall so wenig vorgaben macht wie es geht und ein allgemeines format hat, dass keine layout/designs vorgibt. das ganze geht schon in eine sehr gute richtung, danke dafür.

[alxndr-w]

wie erkennt man eine "umfangreiche Doku"?

Ich meine jetzt eine Doku, die nicht mehr sinnvoll in einer einzelnen README-Datei verwaltet werden kann, bspw. yform

wenn es keine help.inc.php gibt, aber eine README, wird diese als Hilfeseite ausgegeben.

Stimmt. Wäre aber u.U. BC, wenn meine Lösung hier die bisherige ersetzt, da ich mit meiner Lösung auf eine vorgegebene Struktur von Überschriften (und auch Zeilenumbrüchen) angewiesen bin.

"einen standard für README" unterstützt der core bereits, da diese wie in github bereits integriert ist (in teilen zumindest). was meinst du mit "standards.. bei mehrsprachigen seiten"?
[...] das kann github auch, soweit ich weiß. daher 👍

Mehrsprachige Hilfe-Seiten. Mein Vorschlag /docs/README.xx_xx.md. Habe keinen einheitlichen Standard von GitHub gefunden.

ist das was man auf dem Screenshot sieht ein "hilfe-addon" oder eine neue "redaxo core page"?
Prototyp für eine generische Doku-Darstellung - was ist damit gemeint?

Zwei Screenshots mit zwei Prototypischen Umsetzungen. Einmal als übergreifende Hilfe-Seite und einmal alternativ direkt am Addon. Am besten mal den verlinkten Commit ausprobieren, damit man testen kann, wie es sich anfühlt. Das Layout ist ja nah am bisherigen für yform, yrewrite und co.

das macht sinn. hier könnte man überlegen ob man hier das ganze nur haben will für den entwickler des addons selbst oder ob das ein "crowd source" gedanken ist (ähnlich wie in der neuen tricks seite), sodass jeder "aufgefordert wird" änderungen/verbesserungen beizusteuern.

Ich bin da immer für Beteiligung und für das Senken von Hürden. Also öffentlich.

das ist denke ich ein wichtiger punkt, da man schauen muss wie/wo man die bilder (bzw. generell externe resourcen ablegt). falls die bilder irgendwo online liegen würden: ist die readme dann auch für installationen im Intranet ohne www zugang "lesbar"?

Bei dem, was ich von @schuer so gesehen habe, ist das auf https://raw.githubusercontent.com/... abgelegt. Das kann man super gut parsen und lokal auf bspw. /assets/docs/ umleiten.

wenn die inhalte auf github liegen, könnte man hier "live" die autoren aus den repositries abfragen (ähnlich wie in der neuen tricks seite)

Das kann ich nicht umsetzen, hört sich aber gut an!

[alxndr-w]

Ich weiß nicht, wie es hier weitergehen kann.