Guidedog マニュアル 0.2.0
言語
このページの内容
Guidedog / ドキュメント 0.2.0

文書を書く

Guidedog は reStructuredText（.rst）と MyST Markdown（.md）に対応します。共通の意味構造を持つ文書ツリーに解析し、HTML サイトと PDF の本を生成します。

ソース形式の選択

ドメイン、複雑な表、拡張可能なディレクティブには reStructuredText を使います。Markdown の構文で Sphinx 形式のディレクティブやロールも使いたい場合は MyST Markdown を選びます。

プロジェクト内の Markdown は MyST として読みます。単独変換の guidedog convert は、MyST を明示しなければ CommonMark を使います。

見出しと構造

文書のタイトルはページを示し、見出しは本文を区切ります。RST の見出しには下線を使い、同じ上線も付けられます。線は文字列以上の長さにします。

推奨する見出しの記号:

Document Title
==============

Section Heading
---------------

Subsection
~~~~~~~~~~

Sub-subsection
^^^^^^^^^^^^^^

Paragraph Heading
"""""""""""""""""

プロジェクト全体で見出しの階層をそろえます。MyST Markdown では #、##、### を使います。

文字装飾とインライン記法

インライン記法は装飾ではなく、意味を示すために使います。

表 1 インライン記法
書式 reStructuredText MyST Markdown
太字 **strong text** **strong text**
強調・斜体 *emphasized text* *emphasized text*
インラインコード ``inline code`` `inline code`
下付き文字 :sub:`text` {sub}`text`
上付き文字 :sup:`text` {sup}`text`

アスタリスクやバッククォートをそのまま書くには、\*not italic\* のようにバックスラッシュでエスケープします。

リスト

Guidedog は四種類のリストに対応します。

箇条書き

* First item
* Second item with multiple lines
  of continuing explanation.
* Third item

番号付きリスト

1. Numbered item
2. Second item
#. Automatically numbered item
#. Next auto-numbered item

定義リスト

定義リストは用語と説明を組にします。用語を一行で書き、すぐ次に字下げした定義を置きます。

Workspace
   A bounded memory buffer supplied by the caller for document conversion.

Session
   A host-level coordinator that manages memory budgets and document caches.

フィールドリスト

フィールドリストは構造化したメタデータや引数の説明に使います。

:Authors: Jane Doe, John Smith
:Version: 1.2
:Status: Active

コードブロック

code-block または sourcecode で構文を強調したコードを表示します。Guidedog は 35 種類以上の言語に対応します。

.. code-block:: python
   :linenos:
   :caption: Server entry point
   :emphasize-lines: 2, 4-5

   def main():
       app = create_app()
       app.run(host="0.0.0.0", port=8080)

コードブロックのオプション:

  • :linenos:: コードの横に行番号を表示します。
  • :caption: Title: コードの上下にキャプションを付けます。
  • :emphasize-lines: 1, 3-5: 指定した行を強調します。
  • :name: label: コードに参照用のラベルを付けます。

外部のソースをそのまま取り込むには literalinclude を使います。

.. literalinclude:: ../src/server.py
   :language: python
   :lines: 1-25
   :linenos:

注記ブロック

注記ブロックは注意事項、警告、補足を目立たせます。

.. note::
   Helpful background context or implementation detail.

.. tip::
   Suggested best practices or workflow shortcuts.

.. important::
   Essential requirements that must not be overlooked.

.. warning::
   Conditions that could lead to unexpected behavior or lost work.

.. caution::
   Potential pitfalls or sensitive operational steps.

.. seealso::
   References to related chapters, specifications, or external guides.

danger、error、hint、attention も使えます。独自のタイトルには admonition を使います。

.. admonition:: Design Rationale

   Explains why a particular architecture was chosen.

表

Guidedog はシンプルテーブル、グリッドテーブル、ディレクティブによる表に対応します。

シンプルテーブル

シンプルテーブルは横線で列の範囲を示します。

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
True   True   True
=====  =====  =======

グリッドテーブル

グリッドテーブルは複数行のセルや、行・列にまたがるセルを扱えます。

+------------------------+------------+----------+
| Header row, column 1   | Column 2   | Column 3 |
+========================+============+==========+
| Cell with multiple     | Second     | Third    |
| paragraphs of text.    | column     | column   |
+------------------------+------------+----------+

リストテーブル

list-table は入れ子の箇条書きから表を作ります。幅の広い表もソース上で読みやすく、変更を管理しやすくなります。

.. list-table:: Project configurations
   :widths: 25 25 50
   :header-rows: 1

   * - Target
     - Builder
     - Description
   * - Website
     - ``html``
     - Static HTML documentation site
   * - Book
     - ``pdf``
     - Typeset PDF book powered by Typst

CSV テーブル

csv-table はカンマ区切りのデータから表を作ります。

.. csv-table:: Comparative metrics
   :header: "Name", "Time (ms)", "Memory (MB)"
   :widths: 40, 30, 30

   "Cold build", 42, 12
   "Incremental", 3, 4

画像と図

image と figure で画像、スクリーンショット、図を挿入します。

.. image:: /assets/architecture.png
   :width: 600px
   :align: center
   :alt: System architecture diagram

.. figure:: /assets/flow.png
   :scale: 80%
   :align: center
   :alt: Execution flowchart

   Data flows sequentially through reader, resolver, and renderer.

figure は画像にキャプションを付け、参照用のラベルも指定できます。

目次ツリーで構成する

toctree は文書の階層、ナビゲーション、HTML と PDF の読み順を定義します。

.. toctree::
   :maxdepth: 2
   :caption: User Guide
   :numbered:

   installation
   quickstart
   configuration

toctree の主なオプション:

  • :maxdepth: N: 目次に含める見出しの深さ。
  • :caption: Title: ナビゲーション項目の上に表示する分類名。
  • :numbered:: 章と見出しに番号を付けます。
  • :titlesonly:: 文書のタイトルだけを並べ、内部の見出しは省きます。
  • :hidden:: 本文内にリストを表示せず、読み順だけを記録します。
  • :glob:: tutorials/* のようなワイルドカードで文書を選べます。

置換と取り込み

再利用する語句、記号、画像を定義します。

.. |version| replace:: 1.0.0
.. |brand| replace:: **Field Notes**

Welcome to |brand| version |version|.

複数のファイルで reStructuredText の内容を共有します。

.. include:: ../shared/warnings.rst

MyST Markdown を書く

MyST Markdown はフェンス付きのブロックで、同じディレクティブやロールを表現します。

# Project overview

Here is a paragraph with **bold text**, *italic emphasis*, and `inline code`.

```{note}
This note is rendered identically to a reStructuredText note directive.
```

```{code-block} python
:caption: Example function
:linenos:

def add(a, b):
    return a + b
```

```{toctree}
:maxdepth: 2
:caption: Navigation

first-chapter
second-chapter
```

See {ref}`storage-model` or consult the {doc}`../reference/configuration`.