# Erstellen offizieller Dokumente Folien: https://hackmd.io/@planetmija/rkf0OoWIO --- ## Agenda - Welche Standards eignen sich für Dokumentationen - Was wird benötigt? - Pro/Contra - Versionierung - Beispiele --- ## Welche Formate - Docx/ODT - Latex - Markdown/Asciidoc/reStructuredText - (textile/mediawiki) ...? --- ## Was muss das Format leisten - Offener Standard - Muss von mehreren Personen (auch gleichzeitig) bearbeitet werden können - Mehrere Formate für die Verbreitung müssen generiert werden können (PDF, HTML, ...) - Sollte ohne große Konvertierung und Layout-Desaster funktionieren - Totzdem sollte pandoc das Format zum Konvertieren unterstützen - Versionierung und Nachverfolgbarkeit --- ## Docx/ODT - Pro: - (WYSIWYG) - Zussamenarbeit: Google Doc / Onlyoffice - PDF-Export - Contra: - Wo soll ich anfangen... --- ## Latex - Pro - (Kein WYSIWYG) - Zusammenarbeit: Overleaf - PDF - Sauberes Layout --- ## Latex - Contra - kein natives HTML - nicht trivial zu verwenden - viele Möglichkeiten eine Sache zu erledigen, z.B: Tabellen, Code - macht Konvertierung schwierig - pandoc kann nicht alles übersetzen (z.B. lstlisting mit Highlighting) --- ## Markdown - Pro - Einfach - Zusammenarbeit: HackMD (siehe Foliensatz) und freie Varianten (CodiMD inzwischen HedgeDoc) - HTML mit Jekyll (z.B. Github Pages) - Generell breite Unterstützung bei Github/Gitlab etc. --- ## Markdown - Contra - Welches MD? Kein einheitlicher Standard, sondern viele Dialekte wie GFM und kramdown - benötigt teilweise HTML für Warnings, Tabellen, etc. - Je nach implementiertem Dialekt/Flavor sieht man das Dokument korrekt oder auch nicht - nicht einfach transferierbar in andere Formate --- ## AsciiDoc/reStructuredText - Pro - Speziell für Dokumentationen entwickelt - können mit pandoc jeweils transferiert werden - HTML, PDF als Ausgabeformate unterstützt - unterstützen Tabellen, Warnungen, Code, ... - kein Mix mit HTML notwendig --- ## AsciiDoc/reStructuredText - Contra - Zusammenarbeit: Keinen Online-Editor gefunden, derzeit nur async - Es existieren Möglichkeiten für Sitzungn mit Atom und OSS, z.B. CodeTogether - nicht so viele Möglichkeiten und nicht so flexibel wie Latex oder Word --- ## AsciiDoc (teilweise subjektiv) - RST kompliziertere Tabellen (subjektiv) - ADOC bzw. AsciiDoctor sieht moderner aus und funktioniert mit Ruby - Könnte Vorteile bei Webseiten mit eigenem Theme sein - jekyll-asciidoc für einene Seite mit Jekyll - kann trotzdem schlecht aussehen wg. Theme (s. späteres Beispiel) - pandoc kann nicht von **ADOC** zu anderen Formaten transferieren! --- ## reStructuredText - Readthedocs kann auf Github zugreifen - Seite kann auf RTD und Github Pages liegen - RST unterstützt auch Markdown (myst_parser) für einfache Seiten - Commommark wie HackMD aber leicht andere Erweiterungen - Erzwingt guten Code und sauberes Layout - Wird vermutlich deswegen als kompliziert angesehen --- ## .rst und .md - myst_parser verwendet markdown-it-py-Parser, der auf CommonMark basiert - https://myst-parser.readthedocs.io/en/latest/using/syntax.html - HackMD und HedgeDoc (ehem. CodiMD) verwenden ebenfalls markdown-it - https://hackmd.io/@codimd/markdown-syntax - Jeweils eigene CommonMark-Erweiterungen --- ## Sphinx - Sphinx unterstützt RST und MD - https://www.sphinx-doc.org - Wird vom Executable Book Project verwendet - Soll für Publikationen rund um Jupyter verwendet werden - https://executablebooks.org --- ## Diskussionsvorschlag - Verwendung von CommonMark oder reStructuredText - letzteres für eindeutige Konvertierung - Ermöglich Editoren wie HackMD/HedgeDoc - Bei den Syntax-Erweiterungen eher an MySt orientieren --- ## Versionierung - Git: Github und Gitlab - Tags für veröffentlichte und abgesegnete Versionen - ORCID + DOI in "getaggten" Versionen - Github/Gitlab sind oft bereits integriert, z.B. RTD und HackMD - Overleaf kann auch mit Git versioniert/kontrolliert werden - Traffic Light Protocol muss mit Sichtbarkeit angestimmt werden (Historie) --- ## Beispiele für Tabellen kramdown und CommonMark ``` kramdown: CommonMark: |--- |A|B |A|B |-|- |-|- |1|2 |1|2 |3|4 |3|4 |=== ``` |A|B |-|- |1|2 |3|4 --- ## Beispiele für Tabellen AsciiDoc (inkl. colspan) ``` [width="20%", options="header"] |=== |A|B |1|2 |3|4 |=== [width="20%", options="header"] |=== 2+|title |1|2 |=== ``` --- ## Beispiele für Tabellen RST (inkl. colspan) ``` == == +---+---+ A B | A | B | == == +===+===+ 1 2 | 1 | 2 | 3 4 +---+---+ == == | 3 | 4 | +---+---+ +-------+ | title | +===+===+ | 1 | 2 | +---+---+ ``` --- # Text einbinden * Mit der Anweisung `.. only::` ([rST](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags)) ``` .. only:: test and html This text is only shown when using html and test ``` * [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#directives-a-block-level-extension-point) ``` ```{only} test and html This text is only shown when using html and test ``` ``` --- ## Code für MyST und rST - [rST Beispiel](https://myst-parser.readthedocs.io/en/latest/examples/wealth_dynamics_rst.html) - [rST Code zum Beispiel](https://myst-parser.readthedocs.io/en/latest/_sources/examples/wealth_dynamics_rst.rst.txt) - [MyST Beispiel](https://myst-parser.readthedocs.io/en/latest/examples/wealth_dynamics_md.html) - [MySt Code zum Beispiel](https://myst-parser.readthedocs.io/en/latest/_sources/examples/wealth_dynamics_md.md.txt) --- ## Beispiele für Dokumentationen - jekyll-asciidoc und Bluma Clean Theme  --- ## Beispiele für Dokumentationen - [Github Pages und kramdown](https://nemo-cluster.github.io/betriebskonzept-nemo/) - [reStructuredText mit Github Actions und RTD Theme](https://nemo-cluster.github.io/nemo-docs/) - [gleicher reStructuredText Artikel über readthedocs.io](https://nemo-documentation.readthedocs.io/en/latest/) - Github unterstützt mehrere "Sprachen": - https://github.com/nemo-cluster/nemo-docs/blob/main/docs/betriebskonzept.rst --- ### DANKE! :sheep: https://cluster.nemo.uni-freiburg.de/