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. If you don’t follow these guidelines, we will not accept your document.

Titel

All pages must have a document title that will be shown in the table of contents (left sidebar) and at the top of the page.

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.

Page titles are underlined with equals signs. For example, the markup for Fehler melden includes the following title:

Bug reporting
=============

Note that:

  1. The title is sentence cased
  2. The title is underlined with equals signs
  3. The underline spans the title completely without going over

Incorrect examples of titles include:

  • Incorrect casing

    Bug Reporting
    =============
    
  • Underline too short

    Bug reporting
    =====
    
  • Underline too long

    Bug reporting
    ================
    

Headings

There are several levels of headings that you may place on your page. These levels are shown here in order:

Page title
==========

Level one
---------

Level two
^^^^^^^^^

Level three
"""""""""""

Each heading level creates a sub-section in the global table of contents tree available when the documentation is built. In the primary (web) version of the documentation, this only shows four levels deep from the top level of the documentation. Please refrain from using more heading levels than will show in this tree as it makes navigating your document difficult. If you must use this many heading levels, it is a good sign that your document should be split up into multiple pages.

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.

You can do this by adding the page to the index.rst file in the same directory that you created it. For example, if you create a file called „newpage.rst“, you would add the line marked with a chevron (>) in the nearest index:

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

Your edits must not introduce any warnings into the documentation build. If any warnings occur, the build will fail and your pull request will be marked with a red ‚X‘. Please ensure that your RST is valid and correct before you create a pull request. This is done automatically (via sphinx-build crashing with your error) if you follow our build instructions below.

Line length

There is no restriction on line length in this repository. Please do not break lines at an arbitrary line length. Instead, turn on word wrap in your text editor.

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

This section lists the TODOs that have been included in this documentation. If you know how to fix one, please send us a Pull Request to make it better!

Um ein todo zu erzeugen, fügt man diese Textauszeichnung zur Seite hinzu:

.. todo:

   My todo text

Zu tun

Der rootstock-Link muss auf UBports umgebogen werden, sobald der actuallyfixit-PR eingepflegt ist.

(Der ursprüngliche Eintrag steht in /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-german/checkouts/latest/porting/installing-16-04.rst, Zeile 28.)