Guidedog / Dokumentation 0.2.0

Dokumente verfassen¶

Guidedog unterstützt reStructuredText (.rst) und MyST Markdown (.md). Beide werden in einen gemeinsamen semantischen Dokumentbaum eingelesen, aus dem HTML und PDF entstehen.

Das Quellformat wählen¶

Verwenden Sie reStructuredText für Domänen, komplexe Tabellen und erweiterbare Direktiven. MyST Markdown verbindet Markdown-Syntax mit Direktiven und Rollen nach Sphinx-Art.

Im Projekt wird Markdown als MyST gelesen. guidedog convert verwendet standardmäßig CommonMark, sofern MyST nicht ausdrücklich gewählt wird.

Überschriften und Struktur¶

Der Dokumenttitel bezeichnet die Seite; Abschnitte gliedern den Text. RST-Überschriften erhalten eine Unterstreichung, optional auch dieselbe Linie darüber. Die Linie darf nicht kürzer als der Titel sein.

Empfohlene Überschriftszeichen:

Document Title
==============

Section Heading
---------------

Subsection
~~~~~~~~~~

Sub-subsection
^^^^^^^^^^^^^^

Paragraph Heading
"""""""""""""""""

Halten Sie Überschriftsebenen im Projekt einheitlich. MyST Markdown verwendet #, ## und ###.

Textformatierung und Inline-Markup¶

Inline-Markup soll Bedeutung vermitteln, nicht bloß verzieren:

Tabelle 1 Inline-Markup¶
Stil	reStructuredText	MyST Markdown
Fettdruck	`strong text`	`strong text`
Betonung / Kursiv	`emphasized text`	`emphasized text`
`Inline-Code`	``inline code``	`inline code`
Tiefstellung	:sub:`text`	{sub}`text`
Hochstellung	:sup:`text`	{sup}`text`

Literale Sternchen und Backticks werden mit einem Rückstrich maskiert: \*not italic\*.

Listen¶

Guidedog unterstützt vier Listenarten:

Aufzählungslisten¶

* First item
* Second item with multiple lines
  of continuing explanation.
* Third item

Nummerierte Listen¶

1. Numbered item
2. Second item
#. Automatically numbered item
#. Next auto-numbered item

Definitionslisten¶

Eine Definitionsliste verbindet Begriffe mit Erklärungen. Der Begriff steht auf einer Zeile, die eingerückte Definition folgt direkt:

Workspace
   A bounded memory buffer supplied by the caller for document conversion.

Session
   A host-level coordinator that manages memory budgets and document caches.

Feldlisten¶

Feldlisten enthalten strukturierte Metadaten und Parameterbeschreibungen:

:Authors: Jane Doe, John Smith
:Version: 1.2
:Status: Active

Codeblöcke¶

code-block oder sourcecode zeigt Code mit Syntaxhervorhebung. Guidedog unterstützt über 35 Programmiersprachen:

.. code-block:: python
   :linenos:
   :caption: Server entry point
   :emphasize-lines: 2, 4-5

   def main():
       app = create_app()
       app.run(host="0.0.0.0", port=8080)

Codeblockoptionen:

:linenos:: Zeigt Zeilennummern neben dem Code.
:caption: Title: Fügt eine Beschriftung über oder unter dem Codeblock ein.
:emphasize-lines: 1, 3-5: Hebt die angegebenen Zeilen hervor.
:name: label: Weist dem Codeblock ein Verweisziel zu.

Mit literalinclude binden Sie externe Quelldateien direkt ein:

.. literalinclude:: ../src/server.py
   :language: python
   :lines: 1-25
   :linenos:

Hinweisblöcke¶

Hinweisblöcke heben Anmerkungen, Warnungen und zusätzliche Ratschläge hervor:

.. note::
   Helpful background context or implementation detail.

.. tip::
   Suggested best practices or workflow shortcuts.

.. important::
   Essential requirements that must not be overlooked.

.. warning::
   Conditions that could lead to unexpected behavior or lost work.

.. caution::
   Potential pitfalls or sensitive operational steps.

.. seealso::
   References to related chapters, specifications, or external guides.

Guidedog unterstützt auch danger, error, hint und attention. Für einen eigenen Titel verwenden Sie admonition:

.. admonition:: Design Rationale

   Explains why a particular architecture was chosen.

Tabellen¶

Guidedog unterstützt einfache Tabellen, Gittertabellen und direktivenbasierte Tabellen.

Einfache Tabellen¶

Einfache Tabellen begrenzen Spalten durch waagerechte Linien:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
True   True   True
=====  =====  =======

Gittertabellen¶

Gittertabellen erlauben mehrzeilige Zellen und verbundene Zeilen oder Spalten:

+------------------------+------------+----------+
| Header row, column 1   | Column 2   | Column 3 |
+========================+============+==========+
| Cell with multiple     | Second     | Third    |
| paragraphs of text.    | column     | column   |
+------------------------+------------+----------+

Listentabellen¶

list-table erzeugt Tabellen aus verschachtelten Listen. Breite Tabellen bleiben dadurch im Quelltext gut lesbar und wartbar:

.. list-table:: Project configurations
   :widths: 25 25 50
   :header-rows: 1

   * - Target
     - Builder
     - Description
   * - Website
     - ``html``
     - Static HTML documentation site
   * - Book
     - ``pdf``
     - Typeset PDF book powered by Typst

CSV-Tabellen¶

csv-table erzeugt eine Tabelle aus kommaseparierten Werten:

.. csv-table:: Comparative metrics
   :header: "Name", "Time (ms)", "Memory (MB)"
   :widths: 40, 30, 30

   "Cold build", 42, 12
   "Incremental", 3, 4

Bilder und Abbildungen¶

Mit image und figure fügen Sie Bilder, Screenshots und Diagramme ein:

.. image:: /assets/architecture.png
   :width: 600px
   :align: center
   :alt: System architecture diagram

.. figure:: /assets/flow.png
   :scale: 80%
   :align: center
   :alt: Execution flowchart

   Data flows sequentially through reader, resolver, and renderer.

figure ergänzt das Bild um eine Beschriftung und ein optionales Verweisziel.

Dokumentstruktur mit Inhaltsbäumen¶

toctree definiert Hierarchie, Navigation und Lesereihenfolge für HTML und PDF:

.. toctree::
   :maxdepth: 2
   :caption: User Guide
   :numbered:

   installation
   quickstart
   configuration

Häufige Optionen von toctree:

:maxdepth: N: Gliederungstiefe im Inhaltsverzeichnis.
:caption: Title: Gruppentitel über den Navigationseinträgen.
:numbered:: Nummeriert Kapitel und Überschriften.
:titlesonly:: Zeigt nur Dokumenttitel, keine inneren Abschnitte.
:hidden:: Erfasst die Lesereihenfolge, ohne eine Liste im Text auszugeben.
:glob:: Erlaubt Dokumentmuster wie tutorials/*.

Querverweise und Links¶

Explizite Zielmarken halten Verweise unabhängig vom Dateinamen stabil.

Zielmarken und `:ref:`¶

Setzen Sie die Zielmarke direkt vor eine Überschrift, Tabelle oder Abbildung:

.. _storage-model:

Storage model
-------------

Caller storage is bounded and measured upfront.

Jedes Projektdokument kann auf dieses Ziel verweisen:

See :ref:`storage-model` for details.
See :ref:`custom link text <storage-model>`.

Dokumentverweise mit `:doc:`¶

Verweisen Sie über den Pfad ohne Dateiendung auf ein anderes Dokument:

Read the :doc:`configuration guide <../reference/configuration>` for details.

Glossarbegriffe mit `:term:`¶

Definieren Sie Begriffe mit glossary:

.. glossary::

   Workspace
      A fixed memory arena allocated by the caller for conversion passes.

   Pass
      An in-memory transformation step operating on the document AST.

Verweisen Sie mit der Rolle :term: auf einen Begriff:

Conversion runs within an allocated :term:`workspace`.

Dateidownloads mit `:download:`¶

Kopiert die Datei in den Downloadordner und erzeugt einen Link:

Download the :download:`starter template <files/starter.toml>`.

Externe Links¶

Verweisen Sie auf externe Webadressen:

Visit `Typst <https://typst.app>`_ for typography details.

Ersetzungen und Einbindungen¶

Definieren Sie wiederverwendbare Texte, Symbole oder Bilder:

.. |version| replace:: 1.0.0
.. |brand| replace:: **Field Notes**

Welcome to |brand| version |version|.

So verwenden Sie reStructuredText-Inhalt in mehreren Dateien:

.. include:: ../shared/warnings.rst

MyST Markdown verfassen¶

MyST Markdown verwendet umzäunte Blöcke für dieselben semantischen Direktiven und Rollen:

# Project overview

Here is a paragraph with **bold text**, *italic emphasis*, and `inline code`.

```{note}
This note is rendered identically to a reStructuredText note directive.
```

```{code-block} python
:caption: Example function
:linenos:

def add(a, b):
    return a + b
```

```{toctree}
:maxdepth: 2
:caption: Navigation

first-chapter
second-chapter
```

See {ref}`storage-model` or consult the {doc}`../reference/configuration`.