Ein kleines Buch erstellen¶
Eine Site ist ein Dokumentgraph. Ein Buch braucht eine Lesereihenfolge. Ein toctree liefert beides.
Ein Kapitel hinzufügen¶
Erstellen Sie 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.
Ersetzen Sie den Inhalt von notes/index.rst durch:
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`.
Der Dokumentname lässt .rst weg. Ein Label benennt eine Idee im Dokument. Für Kapitel verwenden Sie Dokumentlinks, für einzelne Argumente Labels.
Ein Diagramm hinzufügen¶
Fügen Sie dies in measurement.rst ein:
.. 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 verwendet die eingebundene Graphviz-Bibliothek. HTML erhält SVG, PDF ein Bild. Ein Diagramminterpreter im Browser ist unnötig. Die Bildunterschrift erklärt die Folgerung, der Alternativtext die Zeichnung.
Das Buch bauen¶
guidedog build html notes -W
guidedog build pdf notes -W
Das Kapitel erscheint in der Seitenleiste und im Inhaltsverzeichnis des Buchs. Folgen Sie dem Abschnittslink im Browser und prüfen Sie sein Ziel im PDF.
Als Nächstes hilft Dokumente verfassen. Halten Sie Kapitel so kurz, dass sie ein Thema erklären.