Zum Inhalt

Styleguide für die Dokumentation

Dieser Leitfaden enthält Informationen über den erwarteten Stil, die MkDocs-spezifische Syntax, verschiedene erforderliche Werkzeuge und die Übersetzung der Dokumentation im Hinblick auf das Schreiben neuer Inhalte und die Übersetzung vorhandener Inhalte.

Allgemeiner Stil

  • Bei Überschriften und Titeln sollte nur das erste Wort groß geschrieben werden.
  • Wir bevorzugen die US-amerikanische Rechtschreibung, mit einigen Freiheiten für programmierspezifische Umgangssprache (z. B. "Apps") und Verben von Substantiven (z. B. "scrollable").
  • Die Schreibweise von "Artefakt" und "Artefakte" ist wie gezeigt.
  • Wir verwenden nach einem Punkt ein einzelnes Leerzeichen.
  • Wir verwenden einen einzelnen Bindestrich, der von Leerzeichen umgeben ist, als Gedankenstrich (oder ein HTML-Literal „—“).
  • Jeder Verweis auf einen Produktnamen sollte die bevorzugte Großschreibung des Produkts verwenden. (z.B. "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • Wenn ein Begriff "als Code" verwendet wird, dann sollte er als Inline-Code zitiert werden, indem er in einzelne Backticks eingeschlossen wird, anstatt dem Wörterbuch hinzugefügt zu werden.
  • Wir vermeiden Begriffe wie „einfach“, „nur“ oder „leicht“, wenn wir Handlungen beschreiben, die ein Benutzer ausführen soll. Diese Begriffe können als abwertend empfunden werden, insbesondere wenn ein Benutzer Schwierigkeiten hat.

Querverweisende Informationen

Wann immer möglich, sollten Sie in der Dokumentation auf Inhalte verweisen. In diesem Abschnitt werden die verschiedenen Möglichkeiten erläutert, die sich je nach Art der referenzierten Informationen ergeben.

MkDocs rendert standardmäßig Markdown-formatierte Links. Standard Markdown-formatierte Web-Hyperlinks sind wie folgt:

[Link text](https://example.com/)

Sie können dieses Format auch für die Verknüpfung mit einer lokalen Datei verwenden:

[Link text](path/to/file.md)

Um auf bestimmte Abschnitte von Dateien oder die API-Dokumentation zu verweisen, muss das MkDocs-Referenzlink-Format verwendet werden.

Benutzerdefinierte Markdown-Anker und Querverweise auf Inhalte

Markdown generiert Anker für alle Überschriften (alles in einer einzigen Zeile, das mit einem bis sechs #-Symbolen beginnt), basierend auf dem Inhalt der Überschrift. Der für diesen Abschnitt generierte Anker lautet beispielsweise "custom-markdown-anchors-and-content-cross—referencing". Aufgrund der Art und Weise, wie unsere Übersetzungen funktionieren, muss jedoch jedes Mal, wenn auf eine Abschnittsüberschrift verwiesen wird, ein benutzerdefinierter Anker verwendet werden.

MkDocs unterstützt die Darstellung einer Referenz-Link-Syntax, die es Ihnen ermöglicht, mit einem modifizierten Markdown-Link auf verschiedene andere Elemente in der Dokumentation zu verweisen. Dazu gehört unter anderem die Verknüpfung mit benutzerdefinierten Markdown-Kopfzeilen und Textankern.

MkDocs-Referenzlinks sind alle Links, die wie folgt formatiert sind:

[Link text][link-target]

Benutzerdefinierte Kopfzeilen und Inhaltsanker sind erforderlich

Jede Kopfzeile oder jeder Inhaltsabschnitt, auf den im Textinhalt über einen MkDocs-Referenzlink in der BeeWare-Dokumentation verwiesen wird, muss mit einem eigenen Anker versehen werden. Andernfalls besteht die Möglichkeit, dass die Links unterbrochen werden, wenn der Kopfzeileninhalt übersetzt wird.

Wenn Sie auf einen Header-Anker verlinken möchten, müssen Sie einen benutzerdefinierten Anker für den gewünschten Inhalt erstellen. Die allgemeine Syntax für das Setzen eines benutzerdefinierten Ankers lautet wie folgt:

# Header text { #anchor-name }

Die Anpassung des Ankers für diesen Abschnitt auf "benutzerdefinierte Anker" würde zum Beispiel mit der folgenden Formatierung erfolgen:

## Custom Markdown anchors { #custom-anchors }

Sie können auch einen Anker auf allgemeinen Inhalt setzen, einschließlich Text und Codeblocks. Die folgende Formatierung, mit Zeilenumbrüchen oben und unten, sollte über dem Inhalt, zu dem Sie verlinken möchten, eingefügt werden:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Sobald die benutzerdefinierten Verankerungen erstellt sind, können Sie innerhalb desselben Dokuments oder in anderen Teilen der Dokumentation auf sie verweisen.

Standard Markdown wird verwendet, um auf einen Anker in der gleichen Datei zu verlinken, der wie folgt formatiert ist:

[Link text](#anchor-name)

Für die Verknüpfung mit einem Anker in einem anderen Dokument wird der MkDocs-Stil für Referenzverknüpfungen verwendet, der wie folgt formatiert ist:

[Link text][anchor-name]

Die MkDocs-Referenzverknüpfung unterstützt auch Querverweise auf die API-Dokumentation, einschließlich dokumentierter Klassen, Klassenmethoden oder -attribute und spezifischer externer Dokumentationsverweise.

Es gibt mehrere Optionen für die Verknüpfung mit einer dokumentierten Klasse, einer Klassenmethode oder einem Klassenattribut, unabhängig davon, ob Sie die Verknüpfung von derselben Datei oder einer separaten Datei aus vornehmen. Wenn Sie auf Klassen usw. verlinken, müssen Sie Backticks in den ersten Satz eckiger Klammern einfügen, damit der Name als Inline-Code dargestellt wird. Die Backticks sind nur dann nicht erforderlich, wenn Sie benutzerdefinierten Text verwenden, der nicht als Inline-Code wiedergegeben werden soll. Backticks sollten niemals in den zweiten Satz eckiger Klammern eingefügt werden.

Die Verknüpfung mit einer Klasse bei gleichzeitiger Anzeige des Namespace wird wie folgt formatiert:

[`module.ClassName`][]

Die Verknüpfung mit einer Klasse, bei der nur der Klassenname angezeigt wird, ist wie folgt formatiert:

[`ClassName`][module.ClassName]

Die Attribute sind dieselben wie oben, wobei der Name des Attributs eingeschlossen ist. Im Folgenden wird der Namespace angezeigt:

[`module.ClassName.attributename`][]

Wie bei den Klassen ist die Anzeige nur des Attributnamens wie folgt formatiert:

[`attributename`][module.ClassName.attributename]

Methoden sollten mit () nach dem Namespace angezeigt werden und müssen daher anders behandelt werden als Attribute. Im Folgenden ist die geeignete Art und Weise, auf eine Methode zu verweisen:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Im Folgenden wird nur der Klassen- und Methodenname angezeigt. Dies erfordert auch die Einbeziehung der Klammern nach dem Namen:

[`Classname.methodname()`][module.Classname.methodname]

Sie können einen Link zu einer Klasse, einer Methode oder einem Attribut erstellen, während Sie einen beliebigen Text anzeigen, indem Sie dieselbe Methode mit dem entsprechenden Namensraum verwenden. Dies geschieht mit einer Klasse, die wie folgt formatiert ist:

[link text][module.ClassName]

Es ist auch möglich, direkt auf die Python-Kerndokumentation sowie auf die Pillow-Dokumentation zu verlinken. Zum Beispiel, um auf die Dokumentation für int zu verlinken:

[`int`][]

Verknüpfung mit der Pillow Image-Dokumentation:

[`PIL.Image.Image`][]

Tipps zum Codeblock

Sprache und Codehervorhebung

Sie können die Sprache für den im Codeblock enthaltenen Code angeben, indem Sie den Sprachnamen nach den ersten drei Backticks einfügen, ohne Leerzeichen dazwischen. Dies führt zu einer entsprechenden Hervorhebung des Codes, wenn der Code gerendert wird. Um zum Beispiel Python anzugeben, beginnen Sie den Codeblock mit `python.

Konsolenbefehle und die Schaltfläche Kopieren

Wenn Sie Konsolenbefehle oder Befehle mit Ausgabe einschließen, sollten Sie sie als "Konsole" oder "Doscon" bezeichnen, je nachdem, ob Sie ein Unix-ähnliches (einschließlich macOS) oder ein Windows-Betriebssystem beschreiben. Sie können die vom Betriebssystem bereitgestellte Eingabeaufforderung einschließen; nur der Befehl wird kopiert, wenn Sie auf die Schaltfläche "Kopieren" klicken. Wenn Sie z.B. einen Codeblock mit ``console beginnen, und den folgenden Inhalt einschließen:

$ mkdir test
$ ls
test

Wenn Sie dann auf die Kopierschaltfläche des Codeblocks klicken, werden nur die Befehle kopiert, die Eingabeaufforderungen und die Ausgabe werden ignoriert. Auf diese Weise können Sie angeben, dass es sich um Konsolenbefehle handelt, während die Benutzer die Kopierschaltfläche dennoch effektiv nutzen können.

Hervorhebung bestimmter Codezeilen

Sie können bestimmte Codezeilen hervorheben. Um zum Beispiel Zeile 2 hervorzuheben, fügen Sie ein Leerzeichen nach der Sprache ein, gefolgt von {hl_lines="2"}. Ihr Codeblock würde also mit ```python {hl_lines="2"}. Das Ergebnis ist:

import toga
from toga.style.pack import COLUMN, ROW

Sie können mehrere verschiedene Zeilen hervorheben. Zum Beispiel würde python {hl_lines="3 5 9"} die Zeilen 3, 5 und 9 hervorheben. Sie können auch einen Bereich von Zeilen hervorheben. Zum Beispiel hebt python {hl_lines="3-8"} die Zeilen 3 bis 8 hervor. Sie können mehrere Bereiche hervorheben, z. B. mit python {hl_lines="9-18 23-44"}.

Markdown-Elemente, die eine bestimmte Formatierung erfordern

Aufgrund der Art und Weise, wie die Übersetzungsdateien generiert werden, ist es wichtig, die erforderlichen Zeilenumbrüche in die Markdown-Syntax für Ermahnungen, Notizen, Tabulatoren, Jinja-Direktiven, Bildunterschriften und Alignment usw. aufzunehmen.

Ermahnungen und Hinweise

Ermahnungen müssen wie folgt formatiert werden, einschließlich eines Zeilenumbruchs vor und nach Beginn und Ende der Ermahnung:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Dies funktioniert mit allen unterstützten Admonition-Typen auf die gleiche Weise. Beispielsweise erfordern Notiz-Admonitions dieselbe Formatierung und dieselben Zeilenumbrüche:

Content above.

/// note | Note title

Note text here.

///

Content below.

Alle unterstützten Admonitionstypen können als Admonitions verwendet werden.

Inhalt der Registerkarten

Der Inhalt von Registerkarten wird wie folgt formatiert, einschließlich eines Zeilenumbruchs vor dem Beginn und nach dem Ende des Inhaltsblocks:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Ein Tabulator mit einer verschachtelten Ermahnung würde wie folgt formatiert werden, einschließlich eines Zeilenumbruchs vor und nach dem Inhaltsblock:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Zusammengeklappter Inhalt

Zusammengefasste Inhalte werden wie folgt formatiert, einschließlich Zeilenumbrüchen:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Alle unterstützten Admonition-Typen können für zusammengefasste Inhalte verwendet werden, müssen jedoch als „details-admonitiontype“ deklariert werden. Ein zusammengefasster Block vom Typ „note“ wäre also „details-note“ (wie oben gezeigt), ein zusammengefasster Block vom Typ „warning“ wäre „details-warning“ usw.

Jinja-Richtlinien

In der Dokumentation gibt es einige Funktionen, die Jinja-Direktiven im Text verwenden. Alles, was die Jinja-Direktiven verwendet, muss in Zeilenumbrüche eingeschlossen werden. Das BeeWare-Tutorial enthält zum Beispiel Jinja-Bedingungen, die auf Variablen basieren, um zu bestimmen, welche Ermahnung auf der Hauptseite angezeigt werden soll. Diese sind wie folgt formatiert:

Content above.



Content below.

Es gibt auch eine Syntax für die Ersetzung von Symbolen oder Text. Bei dieser Syntax handelt es sich um eine Variable, die in ein Paar passender doppelter geschweifter Klammern eingeschlossen ist und, wenn sie in einer eigenen Zeile steht, einen Zeilenumbruch davor und danach enthalten muss.

Content above.

{{ variable }}

Content below.

Bildformatierung

Für Bilder kann die Breite festgelegt werden, und sie können links, rechts und mittig ausgerichtet werden (mit einem Vorbehalt bei "mittig"). Bilder sollten aus Gründen der Barrierefreiheit immer einen aussagekräftigen Alt-Text enthalten.

Die Einstellung der Breite von 300px auf einem Bild würde wie folgt formatiert werden:

![Image alt text](../path/to/image.png){ width="300px" }

Ein Bild links (oder rechts) auszurichten, würde folgendermaßen formatiert werden:

![Image alt text](../path/to/image.png){ align=left }

Das Hinzufügen einer Bildunterschrift zu einem Bild erfordert einen Zeilenumbruch vor und nach dem Bild und wird wie folgt formatiert:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Das Ausrichten eines Bildes in der Mitte ist mit dem Attribut align nicht möglich. Die Abhilfe besteht darin, dem Bild eine leere Beschriftung folgen zu lassen, damit es zentriert wird. Zwischen den einzelnen Abschnitten sowie davor und danach müssen Sie Zeilenumbrüche einfügen. Die Beschriftung wird wie folgt formatiert:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Plugins mit spezieller Markdown-Formatierung

In den folgenden Abschnitten wird die Verwendung von Plugins beschrieben, die eine bestimmte Markdown-Formatierung erfordern.

Verwendung von Snippets zur Einbindung externer Inhalte

Einzelheiten zum Einbinden externer Inhalte aus einer lokalen Datei oder einer URL finden Sie in der Snippets-Erweiterungsdokumentation. Snippets sollten verwendet werden, solange das Dokument keine Jinja-Direktiven enthält, die ausgeführt werden müssen (die Jinja-Ausführung erfolgt parallel zur Snippets-Verarbeitung, und daher wird jegliches Jinja in der Datei nicht verarbeitet). Snippets ist notwendig, wenn Sie Begrenzungszeichen verwenden möchten, die es Ihnen ermöglichen, bestimmte Teile einer Datei separat einzubinden, z. B. wenn das Quelldokument in Abschnitte unterteilt ist, die getrennt voneinander injiziert werden sollen.

Wichtige Hinweise:

  • Wir verwenden -8<- als Snippets-Bezeichner. Die Dokumentation zeigt mehrere Optionen; bitte folgen Sie unserem Stil.
  • Dateien, die sich in gemeinsamen Inhalten der BeeWare Docs Tools befinden, werden als "lokale" Inhalte behandelt. Daher werden Sie entweder nur den Dateinamen verwenden, wie in -8<- "docs-style-guide.md", oder, wenn sich der Inhalt in einem Unterverzeichnis befindet, nur das Verzeichnis und den Dateinamen, wie in -8<- "style/docs-style-guide.md".
  • Wenn Sie externe Inhalte aus einer Datei auf GitHub über eine URL einbinden, müssen Sie die URL des Rohinhalts verwenden, sonst wird die gesamte Webseite eingebettet, wo immer Sie sie einbinden.

Verwendung von Makros zur Einbindung von Inhalten aus BeeWare Docs Tools freigegebenen Inhalten

Sie können auch Inhalte aus dem gemeinsamen Inhaltsverzeichnis der BeeWare Docs-Tools mit dem Macros MkDocs-Plugin einfügen. Diese Methode ist notwendig, wenn das Dokument Jinja-Direktiven enthält, die ausgeführt werden müssen, und sollte nur in dieser Situation verwendet werden. Sie funktioniert nicht mit externen Inhalten über eine URL. Der Macros-Variablen-Ersetzungsmechanismus funktioniert mit dieser Methode.

Es gibt Optionen für die Einbindung von Inhalten mithilfe von Makros:

  1. Verwenden Sie die include Jinja-Syntax, wenn Sie das Dokument ohne weitere manuelle Änderungen einbinden wollen.

  2. Verwenden Sie die Jinja-Syntax extends, wenn Sie die Jinja-Syntax block in das Dokument aufgenommen haben, die es Ihnen ermöglicht, bestimmte Abschnitte zu überschreiben oder zu ergänzen.

Rechtschreibfehler

Wir verwenden die pyspelling-Rechtschreibprüfung. Sie wird während der Lint-Prüfungen ausgeführt.

Wenn pyspelling ein falsch geschriebenes Wort identifiziert, sollte es in den meisten Fällen im Inhalt der Dokumentation korrigiert werden.

In dem seltenen Fall, dass ein gültiges Wort gefunden wird, das nicht im Wörterbuch "pyspelling" enthalten ist, haben Sie zwei Möglichkeiten:

  1. Wenn es sich um ein Wort handelt, das wahrscheinlich mehrfach verwendet wird, sollten Sie das Wort in alphabetischer Reihenfolge in das Dokument spelling_wordlist im Verzeichnis docs aufnehmen.
  2. Wenn es sich um ein Wort handelt, das wahrscheinlich nicht wieder verwendet wird, können Sie es in ein <nospell> / </nospell>-Tag verpacken, und pyspelling wird es inline ignorieren.