Guidedog / 文档
0.2.0
域¶
域是一组指令和角色，用来描述某种编程语言或知识领域中的对象，并建立交叉引用。
Guidedog 内置了以下 Sphinx 风格的域：
- 标准域 （
std）：命令行选项、环境变量、术语和界面标签等通用对象。 - Python 域 （
py）：模块、类、函数、方法、属性和异常。 - C 域 （
c）：函数、类型、结构体、联合体、枚举、枚举值、变量和宏。 - C++ 域 （
cpp）：类、概念、模板、命名空间、方法和表达式。 - JavaScript 域 （
js）：函数、方法、类和属性。 - Odin 域 （
odin）：原生 Odin 包、过程、结构体、联合体和枚举，见 为 Odin 生成文档。
设置主域¶
在 conf.toml 中用 primary_domain 设置默认域，默认为 "py"。启用后可省略域前缀，例如用 .. function:: 代替 .. py:function::，用 :func:`name` 代替 :py:func:`name`。
在文档中局部切换当前域：
.. default-domain:: c
标准域¶
标准域描述命令行工具、环境变量和文档交叉引用。
指令¶
.. program:: mytool
.. option:: -c <config>, --config <config>
Path to the configuration file.
.. envvar:: GUIDEDOG_THEME
Specifies the default theme stylesheet.
角色¶
:doc:`path`: 按相对路径链接到项目文档。:ref:`label`: 链接到显式目标标签.. _label:。:term:`term`: 链接到glossary中定义的术语。:option:`--config`: 链接到option中描述的命令行选项。:envvar:`VARIABLE`: 链接到envvar中描述的环境变量。:command:`name`: 标记系统命令名。:file:`path`: 标记文件或目录路径，可包含{variable}占位符。:kbd:`Ctrl+C`: 标记键盘按键。:menuselection:`File --> Save As`: 表示菜单操作顺序。:guilabel:`Submit`: 表示按钮或界面元素。:pep:`8`: 链接到 Python 改进提案。:rfc:`7231`: 链接到 IETF RFC 文档。
Python 域¶
Python 域描述 Python 接口和签名。
指令¶
.. py:module:: pipeline.reader
:synopsis: Document reading and normalization.
.. py:class:: DocumentReader(source_path: str, encoding: str = "utf-8")
Base class for document readers.
.. py:method:: parse(content: bytes) -> Document
Parses raw bytes into a document tree.
:param content: Raw source content bytes.
:return: Parsed document tree instance.
:raises ValueError: If the source format is unrecognized.
.. py:attribute:: encoding
:type: str
The character encoding used for text decoding.
支持的指令包括：py:module、py:currentmodule、py:function、py:data、py:class、py:method、py:staticmethod、py:classmethod、py:attribute、py:property、py:exception、py:decorator 和 py:type。
角色¶
:py:func:`name`: 链接到 Python 函数。:py:class:`name`: 链接到 Python 类。:py:meth:`name`: 链接到 Python 类方法或实例方法。:py:attr:`name`: 链接到 Python 属性。:py:data:`name`: 链接到 Python 模块级数据。:py:exc:`name`: 链接到 Python 异常类。:py:mod:`name`: 链接到 Python 模块。
C 域¶
C 域描述 C 语言库和头文件。
指令¶
.. c:namespace:: gd
.. c:struct:: Workspace
A contiguous memory buffer for in-memory document parsing.
.. c:member:: size_t capacity
Total byte size of the storage slab.
.. c:function:: int gd_convert(Workspace *ws, const char *input, char *output, size_t out_len)
Converts source text into HTML.
:param ws: Pointer to the initialized workspace.
:param input: Null-terminated input string.
:param output: Destination buffer.
:param out_len: Size of destination buffer.
:returns: 0 on success, or an error code.
角色¶
:c:func:`name`: 链接到 C 函数。:c:member:`name`: 链接到 C 结构体或联合体的成员。:c:data:`name`/:c:var:`name`: 链接到 C 变量。:c:type:`name`: 链接到 C 的 typedef 或类型。:c:struct:`name`: 链接到 C 结构体。:c:union:`name`: 链接到 C 联合体。:c:enum:`name`: 链接到 C 枚举。:c:macro:`name`: 链接到 C 预处理器宏。
C++ 域¶
C++ 域支持现代 C++ 构造、概念、命名空间和作用域。
指令¶
.. cpp:namespace:: guidedog
.. cpp:concept:: template<typename T> Reader
Specifies requirements for document reader types.
.. cpp:class:: template<typename Allocator> Builder
Constructs AST document nodes.
.. cpp:function:: NodeId add_text(std::string_view text)
Appends text to the active node.
角色¶
:cpp:class:`name`: 链接到 C++ 类或结构体。:cpp:func:`name`: 链接到 C++ 函数或方法。:cpp:member:`name`/:cpp:var:`name`: 链接到成员或变量。:cpp:type:`name`: 链接到 C++ 类型别名或 typedef。:cpp:concept:`name`: 链接到 C++20 概念。:cpp:enum:`name`: 链接到 C++ 枚举。
JavaScript 域¶
JavaScript 域描述浏览器脚本、库和 Node.js 模块。
指令¶
.. js:module:: theme
.. js:class:: ThemeController(options)
Manages color themes and local storage persistence.
.. js:method:: toggleTheme()
Toggles between light and dark modes.
角色¶
:js:func:`name`: 链接到 JavaScript 函数。:js:meth:`name`: 链接到 JavaScript 方法。:js:class:`name`: 链接到 JavaScript 类。:js:data:`name`: 链接到 JavaScript 变量。:js:attr:`name`: 链接到 JavaScript 对象属性。:js:mod:`name`: 链接到 JavaScript 模块。
交叉引用约定¶
域中的交叉引用支持以下修饰符：
- 隐藏前缀 ：在目标前加
~，只显示名称的最后一部分。例如:py:func:`~pipeline.reader.DocumentReader.parse`显示为parse()。 - 当前作用域 ：相对引用先在当前模块或命名空间中查找，再进行全局查找。
- 精确匹配 ：在目标前加
.，从当前模块或所属对象开始查找。