Guidedog / Dokumentation 0.2.0

Domänen¶

Eine Domäne bündelt Direktiven und Rollen zum Beschreiben und Verknüpfen von Objekten einer Sprache oder eines Fachgebiets.

Guidedog bietet native Implementierungen dieser Sphinx-Domänen:

Standarddomäne (std): Kommandozeilenoptionen, Umgebungsvariablen, Begriffe und UI-Beschriftungen.
Python-Domäne (py): Module, Klassen, Funktionen, Methoden, Attribute, Properties und Ausnahmen.
C-Domäne (c): Funktionen, Typen, Strukturen, Unions, Aufzählungen, Aufzählungswerte, Variablen und Makros.
C++-Domäne (cpp): Klassen, Konzepte, Templates, Namensräume, Methoden und Ausdrücke.
JavaScript-Domäne (js): Funktionen, Methoden, Klassen und Eigenschaften.
Odin-Domäne (odin): Odin-Pakete, Prozeduren, Strukturen, Unions und Aufzählungen; siehe Odin dokumentieren.

Primärdomäne festlegen¶

primary_domain in conf.toml legt die Standarddomäne fest; Vorgabe ist "py". Danach kann das Präfix entfallen: .. function:: statt .. py:function:: und :func:`name` statt :py:func:`name`.

So wechseln Sie die Domäne lokal im Dokument:

.. default-domain:: c

Standarddomäne¶

Die Standarddomäne beschreibt Kommandozeilenwerkzeuge, Umgebungsvariablen und Dokumentverweise.

Direktiven¶

.. program:: mytool

.. option:: -c <config>, --config <config>

   Path to the configuration file.

.. envvar:: GUIDEDOG_THEME

   Specifies the default theme stylesheet.

Rollen¶

:doc:`path`: Verweist über einen relativen Pfad auf ein Projektdokument.
:ref:`label`: Verweist auf eine explizite Zielmarke .. _label:.
:term:`term`: Verweist auf einen in glossary definierten Begriff.
:option:`--config`: Verweist auf eine mit option beschriebene Kommandozeilenoption.
:envvar:`VARIABLE`: Verweist auf eine mit envvar beschriebene Umgebungsvariable.
:command:`name`: Kennzeichnet einen Systembefehlsnamen.
:file:`path`: Kennzeichnet Datei- und Ordnerpfade mit möglichen {variable}-Platzhaltern.
:kbd:`Ctrl+C`: Kennzeichnet Tasteneingaben.
:menuselection:`File --> Save As`: Formatiert eine Menüfolge.
:guilabel:`Submit`: Formatiert ein Bedienelement oder einen Button.
:pep:`8`: Verweist auf einen Python Enhancement Proposal.
:rfc:`7231`: Verweist auf einen RFC der IETF.

Python-Domäne¶

Die Python-Domäne beschreibt Python-Schnittstellen und Signaturen.

Direktiven¶

.. py:module:: pipeline.reader
   :synopsis: Document reading and normalization.

.. py:class:: DocumentReader(source_path: str, encoding: str = "utf-8")

   Base class for document readers.

   .. py:method:: parse(content: bytes) -> Document

      Parses raw bytes into a document tree.

      :param content: Raw source content bytes.
      :return: Parsed document tree instance.
      :raises ValueError: If the source format is unrecognized.

   .. py:attribute:: encoding
      :type: str

      The character encoding used for text decoding.

Direktiven sind py:module, py:currentmodule, py:function, py:data, py:class, py:method, py:staticmethod, py:classmethod, py:attribute, py:property, py:exception, py:decorator und py:type.

Rollen¶

:py:func:`name`: Verweist auf eine Python-Funktion.
:py:class:`name`: Verweist auf eine Python-Klasse.
:py:meth:`name`: Verweist auf eine Python-Klassen- oder Instanzmethode.
:py:attr:`name`: Verweist auf ein Python-Attribut.
:py:data:`name`: Verweist auf Python-Daten auf Modulebene.
:py:exc:`name`: Verweist auf eine Python-Ausnahmeklasse.
:py:mod:`name`: Verweist auf ein Python-Modul.

C-Domäne¶

Die C-Domäne beschreibt C-Bibliotheken und Header.

Direktiven¶

.. c:namespace:: gd

.. c:struct:: Workspace

   A contiguous memory buffer for in-memory document parsing.

   .. c:member:: size_t capacity

      Total byte size of the storage slab.

.. c:function:: int gd_convert(Workspace *ws, const char *input, char *output, size_t out_len)

   Converts source text into HTML.

   :param ws: Pointer to the initialized workspace.
   :param input: Null-terminated input string.
   :param output: Destination buffer.
   :param out_len: Size of destination buffer.
   :returns: 0 on success, or an error code.

Rollen¶

:c:func:`name`: Verweist auf eine C-Funktion.
:c:member:`name`: Verweist auf ein C-Struktur- oder Unionmitglied.
:c:data:`name` / :c:var:`name`: Verweist auf eine C-Variable.
:c:type:`name`: Verweist auf einen C-Typedef oder Typ.
:c:struct:`name`: Verweist auf eine C-Struktur.
:c:union:`name`: Verweist auf eine C-Union.
:c:enum:`name`: Verweist auf eine C-Aufzählung.
:c:macro:`name`: Verweist auf ein C-Präprozessormakro.

C++-Domäne¶

Die C++-Domäne unterstützt moderne Konstrukte, Konzepte, Namensräume und Gültigkeitsbereiche.

Direktiven¶

.. cpp:namespace:: guidedog

.. cpp:concept:: template<typename T> Reader

   Specifies requirements for document reader types.

.. cpp:class:: template<typename Allocator> Builder

   Constructs AST document nodes.

   .. cpp:function:: NodeId add_text(std::string_view text)

      Appends text to the active node.

Rollen¶

:cpp:class:`name`: Verweist auf eine C++-Klasse oder Struktur.
:cpp:func:`name`: Verweist auf eine C++-Funktion oder Methode.
:cpp:member:`name` / :cpp:var:`name`: Verweist auf ein Mitglied oder eine Variable.
:cpp:type:`name`: Verweist auf einen C++-Typalias oder Typedef.
:cpp:concept:`name`: Verweist auf ein C++20-Konzept.
:cpp:enum:`name`: Verweist auf eine C++-Aufzählung.

JavaScript-Domäne¶

Die JavaScript-Domäne beschreibt Browserskripte, Bibliotheken und Node.js-Module.

Direktiven¶

.. js:module:: theme

.. js:class:: ThemeController(options)

   Manages color themes and local storage persistence.

   .. js:method:: toggleTheme()

      Toggles between light and dark modes.

Rollen¶

:js:func:`name`: Verweist auf eine JavaScript-Funktion.
:js:meth:`name`: Verweist auf eine JavaScript-Methode.
:js:class:`name`: Verweist auf eine JavaScript-Klasse.
:js:data:`name`: Verweist auf eine JavaScript-Variable.
:js:attr:`name`: Verweist auf eine JavaScript-Objekteigenschaft.
:js:mod:`name`: Verweist auf ein JavaScript-Modul.

Konventionen für Querverweise¶

Domänenverweise unterstützen folgende Modifikatoren:

Präfix ausblenden: ~ vor dem Ziel zeigt nur den letzten Namensteil. :py:func:`~pipeline.reader.DocumentReader.parse` erscheint als parse().
Aktueller Gültigkeitsbereich: Relative Verweise suchen zuerst im aktiven Modul oder Namensraum, danach global.
Exakte Übereinstimmung: Ein vorangestelltes . sucht vom aktuellen Modul oder umschließenden Objekt aus.