sphinx-asdf 0.2.4

基本示例

以下是一个示例布局的软件包

mypackage/
   setup.py
   mypackage/
      schemas/
         example.org/
            custom/
               foo/
                  a.yaml
                  b.yaml
                  c.yaml
               bar/
                  x.yaml
                  y.yaml
                  z.yaml
      ...
   docs/
      conf.py
      schemas.rst

该软件包提供了具有以下前缀 tag:example.org/custom 的标签的架构。架构目录的布局反映了这种命名约定。我们希望为所有架构提供文档。

首先，我们将配置变量添加到我们的 docs/conf.py 文件中

# This variable indicates the top-level directory containing schemas.
# The path is relative to the location of conf.py in the package
asdf_schema_path = "../mypackage/schemas"
# This variable indicates the standard prefix that is common to all schemas
# provided by the package.
asdf_schema_standard_prefix = "example.org/custom"

在 docs/conf.py 文件中设置的变量指示 sphinx-asdf 根据我们在文档中使用的名称在哪里查找架构。

现在，我们在 docs/schemas.rst 中使用 asdf-autoschemas 指令来创建架构文档的目录

.. asdf-autoschemas::

   foo/a
   foo/b
   foo/c
   bar/x
   bar/y
   bar/z

列表中的每一项代表要包含在文档中的架构名称。名称 不是 架构文件的路径，不应包含文件扩展名。名称到实际架构文件的解析由 asdf_schema_path 和 asdf_schema_standard_prefix 配置变量处理。

如果我们愿意，也可以使用多个 asdf-autoschemas 指令

These schemas are part of foo:

.. asdf-autoschemas::

   foo/a
   foo/b
   foo/c

And these schemas are part of bar:

.. asdf-autoschemas::

   bar/x
   bar/y
   bar/z

当 sphinx-build 运行时，sphinx-asdf 插件将自动为每个 asdf-autoschemas 指令中列出的每个架构生成架构文档。在文档中，每个 asdf-autoschemas 指令将被替换为一个包含到每个列表中架构文档链接的目录。

指令设置

虽然 asdf_schema_path 和 asdf_schema_standard_prefix 配置变量设置了全局架构解析设置，但也可能设置每个指令的设置。例如，我们可以这样做

.. asdf-autoschemas::
   :schema_root: ../mypackage/schemas
   :standard_prefix: example.org/custom

这可以消除设置全局设置的需求。它还允许基于每个指令覆盖任何全局设置。

外部引用

架构引用同一软件包中的其他架构将自动转换为生成的文档中的链接。（这假设所有引用都对应于由 asdf-autoschemas 指令明确生成的架构）。然而，有时需要解析对其他软件包中架构的引用。为此提供了 asdf_schema_reference_mapping 配置变量。它允许在具有特定前缀的引用和指向另一个软件包文档的 URL 之间进行映射。

例如，要启用对 ASDF 标准文档的引用解析为链接，请在您的 docs/conf.py 文件中包含以下内容

asdf_schema_reference_mappings = [
    (
        "tag:stsci.edu:asdf",
        "http://asdf-standard.readthedocs.io/en/latest/generated/stsci.edu/asdf/",
    ),
]

内联文档

《asdf-autoschemas》指令会自动生成单个模式文档页面并创建目录表。然而，有时在另一个文档内嵌入模式文档可能很有用。《asdf-schema》指令就是为了这个目的提供的。

以下以描述的包为例，可以使用《asdf-schema》指令在另一个文档中记录单个模式

.. asdf-schema::

   foo/a

《asdf-schema》指令的行为也受全局配置变量《asdf_schema_path》和《asdf_schema_standard_prefix》的约束。指令还接受与《asdf-autoschemas》相同的《:schema_root:和《:standard_prefix:参数，用于指令配置（参见上文的《指令设置》）。