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. Dokumente, die diesen Richtlinien nicht folgen, werden nicht akzeptiert.

Titel

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

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:

  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.

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