Dokumentation schreiben

[raphiz]

• Mit readthedocs. und im docs/ Verzeichnis.
• Saubrere Readme (Who? What? Why?)
• Maintaier Kontakt (Bsp. connect@openhsr.ch)

Möglicher Aufbau:

• Übersicht: Was macht connect und was nicht
  • Begriffe / Glossar
  • (Grafische) Benutzerschnittelle
• Installation (Empfohlen via Paketmanager + manuelle Installation)
• Tutorials / Guides
  • Neues Modul/Kurs/Ordner zur Synchronisation
  • Logindaten
    • Initial
    • Ändern (Passwort und username)
    • Hintergrund (Wird im Keyring gespeichert)
  • Wie Drucken
• CLI Doku (= "man pages")
• Wie mithelfen?
  • Vor grossen Änderungen Maintainer kontaktieren (Siehe Checkliste Website)
• Entwickler
  • Architektur / Konzepte
  • Lokale Dev-Umgebung anzeigen
  • Tests laufen lassen
  • Releases machen
  • ...

Links

• A documentation crash course

[mattbaumann]

Hier noch zwei Fragen zum Config-File:

1. /home/rzi/HSR/module//skript/ ist der essentiell? Oder kann ich auch /home/rzi/HSR/module/ schreiben, wenn ich kein skript Folder im AD1 Verzeichnis möchte?
2. Was macht exclude im Node repositories?

Danke.

[Excape]

@mattbaumann

1. Der Ziel-Ordner kann einmal auf globaler Ebene mit default-local-dir angegeben werden. Dann wird <name> mit dem Name des Respositories (in der Beispiel-Config z.B. InfSi1) ersetzt. Für jedes einzelne Repository kann der Ziel-Ort aber mit local-dir überschrieben werden. Dann wird dieser genommen.
2. exclude in den einzelnen Repositories werden zusätzlich zu den global-excludes angefügt. Dies funktioniert momentan so:

• Beginnt der exclude mit einem / (z.B. /Archiv), wird der angegebne Pfad ausgehend vom root des Repositories excluded, im Beispiel also alles unter InfSi1/Archiv/, nicht aber InfSi1/Vorlesungen/Archiv
• Beginnt der Pfad nicht mit einem /, kann er irgendwo im Pfad vorkommen, um excluded zu werden. Mit Archiv wird also auch alles unter InfSi1/Vorlesungen/bla/Archiv excluded
• Alternativ können bestimmte Dateinamen excluded werden. Hier sind Wildcards (*) erlaubt, also z.B *.tmp, file-*.* etc.
• Wichtig: Momentan können Pfadangaben nicht mit Wildcards kombiniert werden, /Archiv/*.txt ist also nicht möglich

Hier ist der Code dazu

[mattbaumann]

Als gute Theme möglichkeit könnten wir später einmal das Read the docs theme verwenden:
read the docs theme.
Dies ist nur als Rand-Notiz gadacht.

[mattbaumann]

Hallo zusammen
Ich gehe davon aus, dass ihr euch heute Abend trefft. Wenn ja, dann könntet Ihr mal die Dokumentation lesen und nach Fehlern suchen in den schon vorhandenen Sites. Ich werde nächste Woche vorbei kommen und wir können dann die "Experten"-Dokumentation besprechen/schreiben.

Bis nächste Woche
mattbaumann

PS: Die connect@openhsr.ch-Mail-Adresse ist noch nicht aufgesetzt nach dem HSR.Mail-System. Ich bräuchte diese, da ich sie in der Dokumentation angegeben habe.

[raphiz]

@mattbaumann Danke! Ich werde heute Abend mal reischauen

[raphiz]

@mattbaumann sorry, bin gestern nicht durchgekommen mit durchlesen & kommentieren - ist aber nicht vergessen! 😉

[raphiz]

@mattbaumann btw. um das read-the-docs theme zu verwenden kann man auch einfach html_theme = 'default' in der conf.py setzen (Siehe http://docs.readthedocs.io/en/latest/theme.html)

[mattbaumann]

@raphiz Thanks.

[mattbaumann]

@openhsr/contributors
Da es so scheint, dass der Treffpunkt eingestellt wurde. Würde ich alle Programmierer einladen, die Dokumentation (Experte) zu schreiben. Da ich mich zurzeit um Dokumentation kümmere, weiss ich nicht was euch wichtig ist in euer Dokumentation.

Grüsse
Matthias Baumann