Crear un libro pequeño¶
Un sitio es un grafo de documentos. Un libro necesita un orden de lectura. Una toctree proporciona ambos.
Añadir un capítulo¶
Cree notes/measurement.rst:
Measurement
===========
A measurement has a value and a unit.
Write both. A bare number leaves the reader guessing.
.. _measurement-units:
Units
-----
Keep one unit within a comparison.
Sustituya el contenido de notes/index.rst por lo siguiente:
Field Notes
===========
These notes explain how to make a comparison that another person can check.
.. toctree::
:maxdepth: 2
:numbered:
measurement
Begin with :doc:`measurement`.
For the unit rule, see :ref:`measurement-units`.
El nombre del documento omite .rst. La etiqueta nombra una idea dentro del documento. Use enlaces de documento para capítulos y etiquetas para argumentos concretos.
Añadir un diagrama¶
Añada lo siguiente a measurement.rst:
.. graphviz::
:caption: A comparison needs a common unit.
:alt: Values are converted to one unit before they are compared.
digraph comparison {
rankdir=LR;
"values" -> "common unit" -> "comparison";
}
Guidedog utiliza su biblioteca Graphviz enlazada. El resultado es SVG en HTML y una imagen en PDF; no hace falta interpretar diagramas en el navegador. El pie explica la conclusión y el texto alternativo, el dibujo.
Compilar el libro¶
guidedog build html notes -W
guidedog build pdf notes -W
El capítulo aparece en la barra lateral y en el índice del libro. Siga el enlace de sección en el navegador y compruebe su destino en PDF.
El siguiente paso útil es Redactar documentos. Mantenga los capítulos lo bastante breves para explicar un tema.