sphinx-asdf 0.1.0rc8

基本示例

以具有以下布局的包为例：

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 packageasdf_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

列表中的每个项表示要包含在 文件。这些名称是not到架构文件的路径，不应该 包括文件扩展名。将名称解析为实际架构文件是 由asdf_schema_path和^{tt7}处理$ 配置变量。

如果愿意，我们还可以使用多个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-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全局配置 变量。该指令还接受相同的:schema_root:和 :standard_prefix:参数作为asdf-autoschemas（请参见上面的Directive settings），用于每个指令配置。