Guidedog / Documentación 0.2.0

Redactar documentos¶

Guidedog admite reStructuredText (.rst) y MyST Markdown (.md). Ambos se analizan en un árbol semántico común que genera HTML y PDF.

Elegir el lenguaje de origen¶

Use reStructuredText para dominios, tablas complejas y directivas extensibles. Elija MyST Markdown si prefiere Markdown sin renunciar a directivas y roles al estilo de Sphinx.

En un proyecto, Markdown se interpreta como MyST. guidedog convert usa CommonMark por defecto, salvo que se seleccione MyST expresamente.

Títulos y estructura¶

El título identifica la página; las secciones organizan el texto. En RST se subraya el título y puede añadirse una línea igual encima. La línea no debe ser más corta que el título.

Marcas de título recomendadas:

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

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

Subsection
~~~~~~~~~~

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

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

Mantenga los niveles de título coherentes. En MyST Markdown use #, ## y ###.

Formato e indicaciones en línea¶

Use las marcas en línea para comunicar significado, no solo para decorar:

Tabla 1 Marcas en línea¶
Estilo	reStructuredText	MyST Markdown
Negrita	`strong text`	`strong text`
Énfasis / cursiva	`emphasized text`	`emphasized text`
`Código en línea`	``inline code``	`inline code`
Subíndice	:sub:`text`	{sub}`text`
Superíndice	:sup:`text`	{sup}`text`

Para escribir asteriscos o comillas invertidas literalmente, use una barra inversa: \*not italic\*.

Listas¶

Guidedog admite cuatro tipos de listas:

Listas con viñetas¶

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

Listas numeradas¶

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

Listas de definiciones¶

Una lista de definiciones empareja términos y explicaciones. Escriba el término en una línea y su definición sangrada justo después:

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

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

Listas de campos¶

Las listas de campos expresan metadatos estructurados y descripciones de parámetros:

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

Bloques de código¶

Use code-block o sourcecode para código resaltado. Guidedog admite más de 35 lenguajes:

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

Opciones de los bloques de código:

:linenos:: Muestra números de línea junto al código.
:caption: Title: Añade un título encima o debajo del código.
:emphasize-lines: 1, 3-5: Resalta las líneas indicadas.
:name: label: Asigna un destino de referencia al bloque.

Use literalinclude para incluir código de un archivo externo:

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

Avisos¶

Los avisos destacan notas, advertencias y consejos adicionales:

.. 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 también admite danger, error, hint y attention. Use admonition para un título propio:

.. admonition:: Design Rationale

   Explains why a particular architecture was chosen.

Tablas¶

Guidedog admite tablas simples, de cuadrícula y basadas en directivas.

Tablas simples¶

Las tablas simples delimitan las columnas con líneas horizontales:

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

Tablas de cuadrícula¶

Las tablas de cuadrícula permiten celdas multilínea y combinaciones de filas y columnas:

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

Tablas de listas¶

list-table crea tablas a partir de listas anidadas, facilitando leer y mantener tablas anchas en el código fuente:

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

Tablas CSV¶

csv-table crea una tabla a partir de valores separados por comas:

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

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

Imágenes y figuras¶

Use image y figure para incluir ilustraciones, capturas y diagramas:

.. 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 añade un pie de imagen y, opcionalmente, un destino de referencia.

Estructurar documentos con toctrees¶

toctree define la jerarquía, los menús y el orden de lectura del sitio HTML y del libro PDF:

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

   installation
   quickstart
   configuration

Opciones habituales de toctree:

:maxdepth: N: Profundidad de títulos incluidos en el índice.
:caption: Title: Título de categoría sobre las entradas de navegación.
:numbered:: Numera capítulos y títulos.
:titlesonly:: Muestra solo los títulos de documento, sin sus secciones internas.
:hidden:: Registra el orden de lectura sin mostrar una lista en el texto.
:glob:: Permite seleccionar documentos con patrones como tutorials/*.

Referencias cruzadas y enlaces¶

Las etiquetas explícitas mantienen las referencias estables e independientes del nombre del archivo.

Etiquetas de destino y `:ref:`¶

Coloque la etiqueta justo antes de un título, tabla o figura:

.. _storage-model:

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

Caller storage is bounded and measured upfront.

Puede enlazar ese destino desde cualquier documento del proyecto:

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

Referencias a documentos con `:doc:`¶

Enlace otro documento por su ruta, sin la extensión:

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

Términos del glosario con `:term:`¶

Defina los términos con 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.

Enlace un término con el rol :term::

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

Descargas con `:download:`¶

Copia el archivo al directorio de descargas y crea un enlace:

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

Enlaces externos¶

Enlace direcciones web externas:

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

Sustituciones e inclusiones¶

Defina frases, símbolos o imágenes reutilizables:

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

Welcome to |brand| version |version|.

Para compartir contenido reStructuredText entre archivos:

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

Redactar MyST Markdown¶

MyST Markdown expresa las mismas directivas y roles mediante bloques delimitados:

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