Guidedog / Documentación 0.2.0

Dominios¶

Un dominio reúne directivas y roles para describir y enlazar objetos de un lenguaje o ámbito concreto.

Guidedog incluye implementaciones nativas de estos dominios de Sphinx:

Dominio estándar (std): opciones de línea de comandos, variables de entorno, términos y etiquetas de interfaz.
Dominio Python (py): módulos, clases, funciones, métodos, atributos, propiedades y excepciones.
Dominio C (c): funciones, tipos, estructuras, uniones, enumeraciones, enumeradores, variables y macros.
Dominio C++ (cpp): clases, conceptos, plantillas, espacios de nombres, métodos y expresiones.
Dominio JavaScript (js): funciones, métodos, clases y propiedades.
Dominio Odin (odin): paquetes, procedimientos, estructuras, uniones y enumeraciones de Odin; véase Documentar Odin.

Elegir el dominio principal¶

El dominio predeterminado se fija con primary_domain en conf.toml; por defecto es "py". Permite omitir el prefijo: .. function:: por .. py:function:: y :func:`name` por :py:func:`name`.

Para cambiar el dominio localmente en un documento:

.. default-domain:: c

Dominio estándar¶

El dominio estándar describe herramientas de línea de comandos, variables de entorno y referencias entre documentos.

Directivas¶

.. program:: mytool

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

   Path to the configuration file.

.. envvar:: GUIDEDOG_THEME

   Specifies the default theme stylesheet.

Roles¶

:doc:`path`: Enlaza un documento del proyecto mediante una ruta relativa.
:ref:`label`: Enlaza una etiqueta explícita .. _label:.
:term:`term`: Enlaza un término definido en glossary.
:option:`--config`: Enlaza una opción descrita con option.
:envvar:`VARIABLE`: Enlaza una variable de entorno descrita con envvar.
:command:`name`: Marca un nombre de comando.
:file:`path`: Marca rutas de archivos o directorios con posibles marcadores {variable}.
:kbd:`Ctrl+C`: Marca pulsaciones de teclado.
:menuselection:`File --> Save As`: Da formato a una secuencia de menús.
:guilabel:`Submit`: Da formato a un botón o elemento de interfaz.
:pep:`8`: Enlaza una propuesta de mejora de Python.
:rfc:`7231`: Enlaza un documento RFC del IETF.

Dominio Python¶

El dominio Python describe interfaces y firmas de Python.

Directivas¶

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

Las directivas incluyen py:module, py:currentmodule, py:function, py:data, py:class, py:method, py:staticmethod, py:classmethod, py:attribute, py:property, py:exception, py:decorator y py:type.

Roles¶

:py:func:`name`: Enlaza una función Python.
:py:class:`name`: Enlaza una clase Python.
:py:meth:`name`: Enlaza un método de clase o de instancia de Python.
:py:attr:`name`: Enlaza un atributo Python.
:py:data:`name`: Enlaza datos de módulo de Python.
:py:exc:`name`: Enlaza una clase de excepción Python.
:py:mod:`name`: Enlaza un módulo Python.

Dominio C¶

El dominio C describe bibliotecas y cabeceras de C.

Directivas¶

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

Roles¶

:c:func:`name`: Enlaza una función C.
:c:member:`name`: Enlaza un miembro de estructura o unión de C.
:c:data:`name` / :c:var:`name`: Enlaza una variable C.
:c:type:`name`: Enlaza un typedef o tipo C.
:c:struct:`name`: Enlaza una estructura C.
:c:union:`name`: Enlaza una unión C.
:c:enum:`name`: Enlaza una enumeración C.
:c:macro:`name`: Enlaza una macro del preprocesador C.

Dominio C++¶

El dominio C++ admite construcciones modernas, conceptos, espacios de nombres y ámbitos.

Directivas¶

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

Roles¶

:cpp:class:`name`: Enlaza una clase o estructura C++.
:cpp:func:`name`: Enlaza una función o método C++.
:cpp:member:`name` / :cpp:var:`name`: Enlaza un miembro o variable.
:cpp:type:`name`: Enlaza un alias de tipo o typedef de C++.
:cpp:concept:`name`: Enlaza un concepto de C++20.
:cpp:enum:`name`: Enlaza una enumeración C++.

Dominio JavaScript¶

El dominio JavaScript describe scripts del navegador, bibliotecas y módulos Node.js.

Directivas¶

.. js:module:: theme

.. js:class:: ThemeController(options)

   Manages color themes and local storage persistence.

   .. js:method:: toggleTheme()

      Toggles between light and dark modes.

Roles¶

:js:func:`name`: Enlaza una función JavaScript.
:js:meth:`name`: Enlaza un método JavaScript.
:js:class:`name`: Enlaza una clase JavaScript.
:js:data:`name`: Enlaza una variable JavaScript.
:js:attr:`name`: Enlaza un atributo de objeto JavaScript.
:js:mod:`name`: Enlaza un módulo JavaScript.

Convenciones de referencias cruzadas¶

Las referencias de dominio admiten estos modificadores:

Ocultar el prefijo: anteponer ~ muestra solo el último componente. :py:func:`~pipeline.reader.DocumentReader.parse` se muestra como parse().
Ámbito actual: una referencia relativa busca primero en el módulo o espacio de nombres activo y luego globalmente.
Coincidencia exacta: anteponer . busca desde el módulo actual o el objeto contenedor.