Documentation style guide

TODO: Consider reordering content

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

Reference links¶

MkDocs rendert standardmäßig Markdown-formatierte Links. MkDocs unterstützt auch die Darstellung einer Referenzlink-Syntax, die es Ihnen ermöglicht, mit einem modifizierten Markdown-Link auf verschiedene andere Elemente in der Dokumentation zu verweisen. Dies umfasst unter anderem die Verknüpfung mit Standard-Markdown-Kopfverankerungen, benutzerdefinierten Markdown-Kopf- und Textverankerungen, benutzerdefinierten Referenz-IDs, dokumentierten Klassen und Klassenmethoden oder -attributen sowie spezifischen externen Dokumentationsverweisen.

Standardmäßige Markdown-formatierte Links 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)

Die Verknüpfung mit einem Anker in derselben Datei wird wie folgt formatiert:

[Link text](#anchor-name)

Eine Verknüpfung zu einem Anker in einer anderen Datei wird wie folgt formatiert:

[Link text][anchor-name]

Wenn Sie auf einen Anker in einer anderen Datei verlinken müssen und der Ankername in mehreren Dateien doppelt vorkommt, können Sie einen benutzerdefinierten Anker für den gewünschten Inhalt erstellen (wie im nächsten Abschnitt gezeigt) und mit diesem über die Formatierung des Referenzlinks verlinken:

[Link text][custom-anchor-name]

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]

Attributes are the same as above, with the attribute name included. The following displays the namespace:

[`module.ClassName.attributename`][]

As with classes, displaying only the attribute name is formatted as follows:

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

Methods should be displayed with () after the namespace, and therefore must be handled differently than attributes. The following is the appropriate way to link to a method:

[`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]

You can link to a class, method, or attribute while displaying arbitrary text, using the same method with the applicable namespace. Doing this with a class is formatted as follows:

[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`][]

Benutzerdefinierte Markdown-Anker¶

Markdown generates anchors for all headers (anything on a single line starting with between one and six # symbols), based on the content of the header. For example, the anchor generated for this section is custom-markdown-anchors. There are situations where it makes sense to instead set a custom anchor, such as, if you are using the anchor in a reference link, or if the header is overly verbose, and you need something more memorable available for reuse.

Reference links and custom anchors

Any header that is referenced in text content via a MkDocs reference link must have a custom anchor attached. Otherwise, there is the potential to break links when header content is translated.

MkDocs reference links are any links formatted as follows:

[Link text][anchor-name]

Therefore, an example related header must be formatted as follows:

# Header { #anchor-name }

The general syntax for setting a custom anchor is as follows:

# Header text { #anchor }

For example, customizing the anchor for this section to custom-anchors would be done with the following formatting:

## Custom Markdown anchors { #custom-anchors }

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

Content above.

[](){ #anchor-name }

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

Markdown elements that require specific formatting¶

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, including
multi-line text.

A second paragraph.

///

Content below.

Ermahnungen erfordern die gleiche Formatierung und Zeilenumbrüche:

Content above.

/// note | Note

Note text here.

///

Content below.

This format also works for danger, tip, and warning admonition types.

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.

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.

{% if config.extra.translation_type == "original" %}

/// admonition | Admonition title

Text

///

{% endif %}

Content below.

There is also syntax for substituting symbols or text. This syntax is a variable wrapped in a pair of matching double curly braces, and, if on its own line, must include a newline before and after.

Content above.

{{ variable }}

Content below.

Bilder mit Beschriftungssyntax¶

Unabhängig davon, ob die Beschriftungssyntax für die Zentrierung eines Bildes oder für die Bereitstellung einer Bildunterschrift verwendet wird, muss sie zwischen den einzelnen Abschnitten Zeilenumbrüche enthalten.

Wenn Sie zum Beispiel eine leere Bildunterschrift hinzufügen, um ein Bild zu zentrieren, sollten Sie sie wie folgt formatieren, mit einem Zeilenumbruch vor und nach dem Inhaltsblock:

Content above.

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

/// caption

///

Content below.

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

Content above.

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

/// caption

Caption content.

///

Content below.

Code block tips¶

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, können Sie die Eingabeaufforderung einschließen, wenn Sie sie als console oder doscon bezeichnen, je nachdem, auf welches Betriebssystem Sie sich beziehen, und nur der Befehl wird kopiert, wenn Sie auf die Schaltfläche Kopieren klicken. Wenn Sie zum Beispiel einen Codeblock mit "Konsole" 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"}.

Bildformatierung¶

Für Bilder kann die Breite festgelegt werden, und sie können links, rechts und mittig ausgerichtet werden (mit einem Vorbehalt bei "mittig").

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

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

/// caption

///

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:

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

Verwendung von Snippets zur Einbindung externer Inhalte¶

For details on how to include external content from a local file or a URL, see the Snippets extension documentation. Snippets should be used as long as the document does not contain Jinja directives that need to be executed (the Jinja execution happens alongside the Snippets processing, and therefore any Jinja in the file will not be processed). Snippets is necessary if you want to be able to use delimiters that allow you to include specific parts of a file separately, e.g. the source document is divided up into sections to be injected separately from each other.

Important notes:

Wir verwenden -8<- als Snippets-Bezeichner. Die Dokumentation zeigt mehrere Optionen; bitte folgen Sie unserem Stil.
Files found in BeeWare Docs Tools shared content are treated as "local" content, and should be added using only the filename, i.e. this style guide would be included using -8<- "docs_style_guide.md".
If you are including external content from a file on GitHub via a URL, you must use the raw content URL, or it will render the full webpage embedded wherever you include it.

Using Macros to include content from BeeWare Docs Tools shared content¶

You can also include content from the BeeWare Docs tools shared content directory using the Macros MkDocs plugin. This method is necessary if the document contains Jinja directives that need to be executed, and should only be used in this situation. It will not work with external content via a URL. The Macros variable-replacement mechanism works with this method.

There are options for including content using Macros:

Use include. If you want to include the document with no other manual changes to it, you can use the following:
```
{% include "filename.md" %}
```
Use extends. If you have included Jinja in the document that allows you to override specific sections, you will need to include the content using the following:
```
{% extends "filename.md" %}
```

This allows you to use Jinja's block mechanism to override sections of a document.