Make a small book¶
A site is a graph of documents. A book needs a reading order.
A toctree supplies both.
Add a chapter¶
Create 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.
Replace the contents of notes/index.rst with:
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`.
The document name omits .rst. The label names an idea within a document.
Use a document link for a chapter. Use a label for a particular argument.
Add a diagram¶
Put this in 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 uses its linked Graphviz library. The result is an SVG in HTML and an image in the PDF. No browser diagram interpreter is needed. A caption explains the conclusion. Alternative text explains the drawing.
Build the book¶
guidedog build html notes -W
guidedog build pdf notes -W
The chapter is in the sidebar and in the book’s contents. Follow the section link in the browser. Inspect its destination in the PDF.
The next useful step is Authoring documents. Keep chapters small enough to explain one subject.