Guidedog / 文档 0.2.0

编写文档¶

Guidedog 支持 reStructuredText（.rst）和 MyST Markdown（.md）。两者都解析为同一种语义文档树，再生成 HTML 网站和 PDF 图书。

选择源文件语言¶

需要完整的域、复杂表格和指令时，使用 reStructuredText。偏好 Markdown 语法，同时需要 Sphinx 风格的指令和角色时，使用 MyST Markdown。

项目中的 Markdown 使用 MyST 方言。单文件转换 guidedog convert 默认使用 CommonMark，除非显式指定 MyST。

标题与结构¶

文档标题标识页面，章节标题组织正文。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.

Guidedog 也支持 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/*。

交叉引用与链接¶

显式目标标签可保持引用稳定，不依赖文档文件名。

目标标签与 `:ref:`¶

在标题、表格或插图前放置目标标签：

.. _storage-model:

Storage model
-------------

Caller storage is bounded and measured upfront.

项目中的任意文档都可引用此目标：

See :ref:`storage-model` for details.
See :ref:`custom link text <storage-model>`.

用 `:doc:` 引用文档¶

按路径链接到其他文档，省略扩展名：

Read the :doc:`configuration guide <../reference/configuration>` for details.

用 `:term:` 引用术语¶

用 glossary 定义术语：

.. glossary::

   Workspace
      A fixed memory arena allocated by the caller for conversion passes.

   Pass
      An in-memory transformation step operating on the document AST.

用 :term: 链接到术语：

Conversion runs within an allocated :term:`workspace`.

用 `:download:` 提供文件下载¶

将文件复制到下载目录，并生成链接：

Download the :download:`starter template <files/starter.toml>`.

外部链接¶

链接到外部网址：

Visit `Typst <https://typst.app>`_ for typography details.

替换与包含¶

定义可重复使用的短语、符号或图片：

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