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

These rules govern how you should write your documentation to avoid problems with style, format, or linking.

Titel

Alle Seiten müssen einen Dokumententitel haben. Der Titel wird im Inhaltsverzeichnis (linke Randleiste) und im Kopf der Seite angezeigt.

Titles should be „sentence cased“ rather than „Title Cased“. For example:

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:

  1. Nur der erste Buchstabe des Satzes wird groß geschrieben
  2. Der Titel wird mit Gleichzeichen unterstrichen
  3. 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 zum File``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.

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 von ubports/docs.ubports.com auf GitHub durchgeführt werden. Falls nicht klar ist, wie das geht, hilft die exzellenteGitHub-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.

Final check of your contribution

After you have created your PR on github, the CI (continuous integration) system will make a test build of your contribution. Please double check whether this builds successfully and whether the result looks as you intended it to:

  • Scroll to the bottom of the „Conversation“ tab of your PR on github, here you will see the checks (You may have to click on „Show all checks“)
  • It can have a yellow dot, i.e., „pending“ then wait a few more seconds.
  • Or it may have a red X, i.e., it failed. In this case please check why it failed
  • If it shows a green check mark, it means the PR could be built successfully
  • Now please click on „Details“,
  • then „Artifacts“ on the top right,
  • then „_build/html/..index.html“,
  • and finally on „Go to start page“.

Now you can browse a complete build of the UBports docs site with your contribution included. Double check whether your changes look ok.

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

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 49.)