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 でも移動先を確認してください。

次は文書を書くが役立ちます。1 章で 1 つの主題を説明できる長さにしてください。