Guidedog / 文档 0.2.0

制作一本小书¶

站点是文档组成的图，图书则需要阅读顺序。toctree 同时提供两者。

添加章节¶

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

将 notes/index.rst 的内容替换为：

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

文档名省略 .rst。标签命名的是文档中的一个概念。链接整章时用文档链接，链接某段论证时用标签。

添加图表¶

将以下内容放入 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 使用链接的 Graphviz 库。HTML 中显示 SVG，PDF 中显示图片，无需浏览器图表解释器。题注说明结论，替代文本解释图形内容。

构建书籍¶

guidedog build html notes -W
guidedog build pdf notes -W

侧边栏和图书目录中都会出现这一章。在浏览器中点击章节链接，并在 PDF 中检查其目标位置。

接下来可阅读编写文档。保持章节简短，每章讲清一个主题。