Dokumentation#
Tipp
Dokumentationen auf dieser Seite werden in ReStructuredText geschrieben, oder kurz RST. Bitte RST Primer konsultieren, falls einem RST nicht geläufig sein sollte.
Diese Seite leitet zum Schreiben guter Dokumentationen für das UBports-Projekt an, die auf dieser Seite zur Verfügung gestellt wird.
Dokumentationsrichtlinien#
Diese Regeln beschreiben wie die Dokumentation geschrieben werden soll, um Probleme mit Stil, Formatierung oder Verlinkung zu vermeiden.
Titel#
Alle Seiten müssen einen Dokumententitel haben, der im Inhaltsverzeichnis (linke Seitenleiste) und oben auf der Seite angezeigt wird.
Nur der Satzanfang des englischen Titels wird groß geschrieben. Zum Beispiel:
Incorrect casing:
Writing A Good Bug Report
Correct casing:
Writing a good bug report
Correct casing when proper nouns are involved:
Installing Ubuntu Touch on your phone
Die Großschreibung von Wörtern im Titel führt zu Regelunklarheiten. Wird nur der Satzanfang groß geschrieben, herrscht Klarheit. Damit bleibt die Großschreibung im Inhaltsverzeichnis konsistent.
Seitentitel werden mit Gleichzeichen unterstrichen. Z.B. wird Fehler melden wie folgt hervorgehoben:
Bug reporting
=============
Regeln:
Nur der erste Buchstabe des Satzes wird groß geschrieben
Der Titel wird mit Gleichzeichen unterstrichen
Die Unterstreichung ist vollständig und endet mit dem letzten Buchstaben
Fehlerhafte Beispiele von Titeln:
Falsche Groß-/Kleinschreibung
Bug Reporting =============
Unterstreichung ist zu kurz
Bug reporting =====
Unterstreichung ist zu lang
Bug reporting ================
Überschriften#
Es gibt mehrere Ebenen von Überschriften, die auf der Seite platziert werden können. Diese Ebenen sind hier geordnet aufgelistet:
Page title
==========
Level one
---------
Level two
^^^^^^^^^
Level three
"""""""""""
Jede Überschriften-Ebene erzeugt eine Unterabschnitt im globalen Inhaltsverzeichnis, wenn die Dokumentation erzeugt wird. In der primären (web) Version der Dokumentation werden nur die ersten vier Ebenen dargestellt. Bitte daher nicht mehr Ebenen verwenden, als im Inhaltsverzeichnis dargestellt werden, um die Navigation im Dokument nicht zu erschweren. Wenn sehr viele Überschriften-Ebenen benötigt werden, sollte das Dokument in mehrere Seiten gesplittet werden.
Inhaltsverzeichnis#
Niemand wird die neue Seite aufrufen, wenn man sie nicht findet. Da geht es Sphinx nicht anders. Deshalb muss jede neue Seite zu Sphinx Inhaltsverzeichnis hinzugefügt werden.
Dies kann durch Hinzufügen der Seite zur Datei index.rst im selben Verzeichnis erfolgen. Wenn z.B. die Datei „newpage.rst“ erstellt wird, müsste die mit dem Größer-Zeichen (>) markierte Zeile in den nächsten Index eingefügt werden:
.. toctree::
:maxdepth: 1
:name: example-toc
oldpage
anotheroldpage
> newpage
Die Reihenfolge ist dabei entscheidend. Falls die Seite an einer bestimmten Stelle im Inhaltsverzeichnis auftauchen soll, muss es dort entsprechend platziert werden. Im vorherigen Beispiel würde newpage am Ende des Inhaltsverzeichnisses eingefügt werden.
Seiten verschieben#
Manchmal wird es notwendig, eine Seite in der Dokumentation an eine andere Stelle zu verschieben. Im Allgemeinen dient dies der Verbesserung des Dokumentflusses: So ist es z. B. sinnvoller, die Seite hinter einer gerade bearbeiteten Seite eines anderen Abschnittes einzufügen.
Die Leute verlinken jedoch aus vielen Quellen zu unserer Dokumentation, was wir nicht beeinflussen können. Personen können über Blogs, Websites und andere Dokumentationsseiten, deren Links möglicherweise nie aktualisiert werden, hierhergelangen. Es ist keine schöne Erfahrung, einem Link von einer anderen Website zu folgen und auf einer 404-Seite zu landen, um sich selbst überlassen in einer neu strukturierten Dokumentation zurechtfinden zu müssen.
Wir verwenden ein Tool namens Rediraffe, um diese schlechte Erfahrung zu vermeiden. Rediraffe erstellt Weiterleitungsseiten, die einen Benutzer von einem alten, ungültigen Link zu einem neuen, nützlichen Link befördern können. Erstellen Sie einen Weiterleitungslink, wenn Sie den Namen einer Seite ändern oder eine Seite innerhalb der Verzeichnisstruktur der Dokumentation verschieben. Weiterleitungslinks werden erstellt, indem der Dateiname des alten Dokuments und der Dateiname des neuen Dokuments relativ zum Stamm der Dokumentation in der Datei redirects.txt platziert werden.
Wir verwenden den checkdiff Builder von Rediraffe, um sicherzustellen, dass Seiten nicht ohne Weiterleitung aus der Dokumentation gelöscht werden. Dieses Programm wird als Teil des build.sh Skripts im Repository und als Teil unseres automatisierten Build-Prozesses ausgeführt, sobald Sie einen Pull Request senden.
Es folgen einige Beispiele für Fälle, in denen Sie Weiterleitungen erstellen sollten.
Wenn Sie systemdev/calendars.rst nach appdev/calendars.rst verschieben, fügen Sie Folgendes der Datei redirects.txt hinzu:
"systemdev/calendars.txt" "appdev/calendars.txt"
Wenn Sie appdev/clickable.rst auf mehrere Seiten in appdev/clickable/ verschieben, um deutlich mehr Informationen über das Tool bereitzustellen als zuvor, und wenn Sie eine Einführungsseite appdev/clickable/introduction.rst erstellt haben, wäre es in diesem Fall eine gute Idee, die alte Seite auf die neue Einführungsseite weiterzuleiten. Dies kann erreicht werden, indem Folgendes zur Datei redirects.txt hinzugefügt wird:
"appdev/clickable.rst" "appdev/clickable/introduction.rst"
Warnungen#
Änderungen dürfen keine Warnungen bei der Erzeugung der Dokumentation hervorrufen. Falls Warnungen auftreten, schlägt die Erzeugung fehl und der Pull-Request wird mit einem roten ‚X‘ markiert. Bitte sicher stellen, dass das RST gültig und korrekt ist, bevor ein Pull-Request geöffnet wird. Dies geschieht automatisch (wenn sphinx-build auf den Fehler stößt), wenn die Anleitungen befolgt werden.
Zeilenlänge#
Es gibt keine Begrenzung für die Zeilenlänge in diesem Repository. Bitte keinen Zeilenumbruch an einer beliebigen Stelle einfügen.
Arbeitsablauf#
Die folgenden Schritte helfen dabei, einen Beitrag zu dieser Dokumentation zu leisten, nachdem man ein Dokument geschrieben hat.
Bemerkung
Ein GitHub-Konto ist Voraussetzung für diese Schritte. Falls noch nicht geschehen, hier das Konto anlegen.
Forken des Repository#
Fortgeschrittenere Änderungen an der Dokumentation können durch einen Fork (Abspaltung) von ubports/docs.ubports.com auf GitHub durchgeführt werden. Falls nicht klar ist, wie das geht, hilft die exzellente GitHub-Anleitung auf forking projects weiter.
Die Dokumentation erzeugen#
Soll diese Dokumentation lokal erzeugt werden, bevor der Pull Request erstellt wird (was man auch tun sollte), folgt man diesen Anweisungen auf der lokalen Kopie des eigenen Forks vom Repository.
Die Dokumentation kann durch Ausführen von ./build.sh im Wurzelverzeichnis des Repository erzeugt werden. Das Skript erzeugt ebenfalls eine virtuelle Build-Umgebung in ~/ubportsdocsenv, falls noch nicht vorhanden.
Wenn alles gut geht, kann das Verzeichnis _build betreten und index.html geöffnet werden, um die UBports-Dokumentation anzuzeigen.
Hat man Probleme beim Erstellen der Dokumentation, so sollte man zunächst versuchen, die Build-Umgebung zu löschen. Dazu führt man rm-r ~/ubportsdocsenv aus und versucht das Erstellen erneut. Je nachdem, wann das Erstellungsskript zum ersten Mal verwendet wurde, muss der Befehl rm möglicherweise mit sudo ausgeführt werden.
Endkontrolle Ihres Beitrags#
Nachdem Sie Ihren Pull Request auf GitHub erstellt haben, wird das System zur kontinuierlichen Integration (CI) eine Testversion Ihres Beitrags erstellen. Überprüfen Sie bitte genau, ob dies erfolgreich war und ob das Ergebnis wie beabsichtigt aussieht:
Scrollen Sie zum unteren Rand der Registerkarte „Conversation“ (Unterhaltung) Ihres Pull Requests auf GitHub, hier sehen Sie die Überprüfungen (Checks), möglicherweise müssen Sie auf „Show all checks“ (Alle Überprüfungen anzeigen) klicken
Es kann ein gelber Punkt angezeigt werden, d.h. „ausstehend“, dann warten Sie ein paar Sekunden länger.
Oder es wird ein rotes X angezeigt, d.h. es ist fehlgeschlagen. Überprüfen Sie in diesem Fall, warum es fehlgeschlagen ist
Wenn ein grünes Häkchen angezeigt wird, konnte der Pull Request erfolgreich erstellt werden
Klicken Sie jetzt bitte auf „Details“ (Einzelheiten),
dann „Artifacts“ (Werkzeuge) oben rechts,
dann „_build/html/..index.html“,
und schließlich auf „Go to start page“ (Gehe zur Startseite).
Jetzt können Sie eine vollständige Version der UBports docs-Website mit Ihrem Beitrag einsehen. Überprüfen Sie genau, ob Ihre Änderungen in Ordnung sind.
Alternative Methoden zur Beteiligung#
Übersetzungen#
Die Komponenten dieses Dokuments findet man zur Übersetzung auf UBports Weblate.
Dokumente ohne RST-Format schreiben#
Falls man Dokumente für UBports schreiben möchte, sich aber unwohl bei der Verwendung von ReStructuredText fühlt, erstellt man das Dokument ohne Formatierung und teilt es im UBports Forum in einem passenden Abschnitt (wahrscheinlich Allgemein). Es wird sich jemand finden, der den erforderlichen ReStructuredText daraus formt.
Unsicher mit Git#
Falls man ein Dokument in ReStructuredText für UBports geschrieben hat, sich aber unwohl bei der Verwendung von Git oder GitHub fühlt, teilt man es im UBports Forum in einem passenden Abschnitt (wahrscheinlich Allgemein). Es wird sich jemand finden, der das Dokument in die Dokumentation einfügt.
Aktuelle TODOs#
Dieser Abschnitt listet die TODOs auf, die zu dieser Dokumentation hinzugefügt wurden. Falls du weißt, wie einer davon erledigt werden kann, sende uns bitte einen Pull Request, um es zu verbessern!
Um ein todo zu erzeugen, fügt man diese Textauszeichnung zur Seite hinzu:
.. todo::
My todo text
Zu tun
There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It’s a simple qml app that can be easily configured. Creation is almost as simple as ‚classic‘ webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.
(Der ursprüngliche Eintrag steht in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-german/checkouts/latest/appdev/webapp/index.rst, Zeile 19.)
Zu tun
Document the process for Nexus 4 (mako)
(Der ursprüngliche Eintrag steht in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-german/checkouts/latest/systemdev/kernel-hal.rst, Zeile 57.)