Canonical Sphinx扩展

本包提供了一些在Canonical文档（例如，在文档入门包）中使用的Sphinx扩展。

注意： 此包之前称为 lxd-sphinx-extensions，但已重命名为 canonical-sphinx-extensions。

安装

使用以下命令安装包

pip install canonical-sphinx-extensions

提供的扩展

本包提供了几个Sphinx扩展，可以组合或单独使用。

相关链接

此扩展允许按页面添加相关链接（Discourse链接和一般相关链接）。链接作为RST文件中的元数据指定。可以通过调整Sphinx模板在任何输出位置显示这些链接。

启用扩展

将related-links添加到conf.py中的扩展列表中，以启用此扩展

extensions = [
              (...),
             "canonical.related-links"
             ]

如果您想添加Discourse链接，还必须在html_context变量中配置您的Discourse实例的前缀

html_context = {
                (...),
                "discourse_prefix": "https://discuss.linuxcontainers.org/t/"
               }

您可以通过指定字典来配置不同的Discourse前缀

html_context = {
                (...),
                "discourse_prefix": {
                    "lxc": "https://discuss.linuxcontainers.org/t/",
                    "ubuntu": "https://discourse.ubuntu.com/t/"}
                }

将相关链接添加到模板中

该扩展提供了两个可以在模板中使用的函数

• discourse_links(meta.discourse)：返回一个无序列表（<ul>）的Discourse链接。
• related_links(meta.relatedlinks)：返回一个无序列表（<ul>）的相关链接。

例如，要根据Furo主题将相关链接包含在模板中，在您的_templates/page.html文件中放置类似以下代码

{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
   {% set furo_hide_toc_orig = furo_hide_toc %}
   {% set furo_hide_toc=false %}
{% endif %}

{% block right_sidebar %}
<div class="toc-sticky toc-scroll">
   {% if not furo_hide_toc_orig %}
    <div class="toc-title-container">
      <span class="toc-title">
       {{ _("Contents") }}
      </span>
    </div>
    <div class="toc-tree-container">
      <div class="toc-tree">
        {{ toc }}
      </div>
    </div>
   {% endif %}
    {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
    <div class="relatedlinks-title-container">
      <span class="relatedlinks-title">
       Related links
      </span>
    </div>
    <div class="relatedlinks-container">
      <div class="relatedlinks">
        {% if meta.discourse and discourse_prefix %}
          {{ discourse_links(meta.discourse) }}
        {% endif %}
        {% if meta.relatedlinks %}
          {{ related_links(meta.relatedlinks) }}
        {% endif %}
      </div>
    </div>
    {% endif %}
  </div>
{% endblock right_sidebar %}

有关Sphinx中模板工作方式的信息，请参阅Sphinx文档。

输出样式

该扩展附带一个CSS文件，适用于上面给出的模板示例。您可以根据使用的主题和模板覆盖这些样式或定义自己的样式。

指定页面的链接

在页面顶部元数据中指定您的Discourse链接和相关链接。

对于Discourse链接，仅指定主题ID（以逗号分隔的列表）。如果您已定义了多个Discourse前缀，则指定键和ID（例如，abc:1234）。

对于相关链接，指定完整的URL（以逗号分隔的列表）。

链接文本自动提取，也可以使用Markdown语法指定。您还可以指定一个备用的链接文本（使用花括号而不是方括号），仅在无法提取链接标题时使用。请注意，空格将被忽略；如果需要在标题中包含空格，请将其替换为 。如果Sphinx因为元数据值以“[”开头而抱怨，请将整个值用双引号括起来。

以下示例使用MyST语法进行元数据

---
discourse: 1234, abc:56789, abc:[Link text](1234)
relatedlinks: https://www.example.com, [Link text](https://www.example.com), {Backup text}(https://www.example.com)
---

YouTube链接

此扩展添加了一个:youtube:指令，您可以使用它将YouTube视频链接添加到输入文件中的任何位置。

启用扩展

将youtube-links添加到conf.py中的扩展列表中，以启用此扩展

extensions = [
              (...),
             "canonical.youtube-links"
             ]

输出样式

该扩展附带一个CSS文件，实现了p.youtube_link元素的样式。您可以在自己的样式表中覆盖此样式。

添加YouTube链接

要将YouTube链接添加到您的页面，请使用:youtube:指令并指定视频链接。

例如，在MyST语法中

```{youtube} https://www.youtube.com/watch?v=4iNpiL-lrXU
```

要覆盖标题，请添加一个:title:选项。例如

```{youtube} https://www.youtube.com/watch?v=4iNpiL-lrXU
:title: Watch on YouTube!
```

自定义角色

此扩展添加了可以在rST中使用的自定义角色。

目前实现

• spellexception - 将提供的文本包含在<spellexception></spellexception>中，使其能够从拼写检查器中排除。
• literalref - 以代码样式呈现提供的引用，将链接文本从拼写检查器中排除。您可以提供链接（例如，:literalref:`www.example.com`，这将结果为www.example.com作为链接文本和https://www.example.com作为链接URL）或单独的链接文本和URL（例如，:literalref:`xyzcommand <www.example.com>）。
• none - 从输出中排除提供的文本。这对于注释特别有用，尤其是在提供 wokeignore 规则时。

配置选项

此扩展添加了一个 :config:option: 指令，您可以使用它来生成可展开的配置选项，一个指向这些选项的 :config:option: 角色以及一个列出所有配置选项的索引。

启用扩展

将 config-options 添加到您的 conf.py 文件中的扩展列表中，以启用此扩展

extensions = [
              (...),
              "canonical.config-options"
             ]

输出样式

此扩展附带一个 CSS 文件，它实现了用于配置选项样式的类。此 CSS 文件需要定义以下颜色变量

• color-content-foreground：正常文本颜色
• color-link：链接文本颜色
• color-table-border：表格边框颜色
• color-orange：对比颜色（用于表格单元格背景）

您可以在自己的样式表中覆盖这些样式。

添加配置选项

使用 :config:option: 指令添加配置选项。它接受两个参数：配置选项名称和作用域。如果未提供作用域，则默认使用 server。

您必须提供 :shortdesc: 选项。可选选项包括 :type:、:liveupdate:、:condition:、:readonly:、:resource:、:managed:、:required: 和 :scope:（此作用域与参数指定的选项作用域无关）。

您可以在简短描述、选项和主要描述中使用格式化。当值以标记开始，或者您想要防止值被处理（例如，防止 "no" 值转换为 "False"）时，请将值放在引号内。

例如，在MyST语法中

```{config:option} backups.compression_algorithm server
:shortdesc: Compression algorithm for images
:type: string
:scope: global
:default: "`gzip`"

Compression algorithm to use for new images (`bzip2`, `gzip`, `lzma`, `xz` or `none`)
```

有关更多示例，请参阅 https://linuxcontainers.cn/lxd/docs/latest/networks/config_options_cheat_sheet。

链接到配置选项

要链接到配置选项，请使用 :config:option: 角色您无法覆盖链接文本（这也没有太多意义，因为链接文本会显示为代码）。

例如，在MyST语法中

{config:option}`instance:migration.incremental.memory.iterations`

链接到索引

您可以使用 config-options 锚点链接到配置选项索引。

例如，在MyST语法中

{ref}`config-options`

终端输出

此扩展添加了一个 :terminal: 指令，您可以使用它来显示包含命令和输出的终端视图。您可以自定义提示符并配置是否应该换行。

启用扩展

将 terminal-output 添加到您的 conf.py 文件中的扩展列表中，以启用此扩展

extensions = [
              (...),
             "canonical.terminal-output"
             ]

输出样式

此扩展附带一个 CSS 文件，它实现了用于样式化终端输出的类。您可以在自己的样式表中覆盖这些样式。

添加终端视图

要将终端视图添加到您的页面，请使用 :terminal: 指令并指定输入（作为 :input: 选项）和输出（作为指令的主要内容）。主要内容中任何以 :input: 开头的行也被视为输入。

要覆盖提示符（默认为 user@host:~$），请指定 :user:、:dir: 和/或 :host: 选项。要使终端水平滚动而不是换行，请添加 :scroll:。

例如，在MyST语法中

Single command sample:

```{terminal}
:input: single command
:user: root
:host: vm
:dir: /tmp/dir/

output line one
output line two
```

Multiple command sample:

```{terminal}
:user: root
:host: vm
:dir: /tmp/dir/

:input: a command
output line one
output line two

:input: another command
more output
```

过滤目录树

此扩展添加了一个 :filtered-toctree: 指令，它几乎与正常的 :toctree: 指令相同，但允许根据指定的过滤器排除页面。

启用扩展

将 filtered-toc 添加到您的 conf.py 文件中的扩展列表中，以启用此扩展

extensions = [
              (...),
             "canonical.filtered-toc"
             ]

配置过滤器

在您的 conf.py 中的 toc_filter_exclude 变量中定义您想要从文档中排除的过滤器。例如

toc_filter_exclude = ['draft','internal']

您可以使用环境变量或构建参数来区分 conf.py 中 toc_filter_exclude 变量的不同设置。例如

if ('TOPICAL' in os.environ) and (os.environ['TOPICAL'] == 'True'):
    toc_filter_exclude = ['diataxis']
else:
    toc_filter_exclude = ['topical']

使用 :filtered-toctree: 指令

:filtered-toctree: 指令与正常的 :toctree: 指令功能相同，但可以在每一行添加过滤器。过滤器必须以冒号 (:) 开头和结尾，中间包含任何字符串。冒号之间的字符串是您在 toc_filter_exclude 变量中指定的内容（然而，您可以使用任何字符串，即使它没有在 toc_filter_exclude 变量中指定）。

您可以将过滤器放在行的开头，或者在文件名或路径之前。每行只能指定一个过滤器。

例如，在MyST语法中

```{filtered-toctree}
:maxdepth: 1

:internal:/tutorial/first_steps
:draft:Installation </installing>
Get support <:external:/support>
```

在这种情况下，所有三个主题都将默认包含。当设置 toc_filter_exclude = ['draft','internal'] 时，只有 获取支持 将被包含。

贡献者列表

此扩展允许添加一个链接，显示页面的所有贡献者。贡献者是从每个文件的 Git 历史中检索的。可以通过修改 Sphinx 模板在输出中的任何位置显示此链接。

启用扩展

将 canonical.contributor-listing 添加到 conf.py 中的扩展列表中，以启用该扩展

extensions = [
              (...),
             "canonical.contributor-listing"
             ]

然后，您可以通过设置 html_context 变量中的 display_contributors 字段来控制是否显示贡献者

html_context = {
                (...),
                "display_contributors": True,
               }

您可以通过指定 display_contributors_since 的值来配置检索贡献者的时间范围

html_context = {
                (...),
                "display_contributors_since": "3 months",
                }

将贡献者链接添加到模板

此扩展提供了一个 get_contributors_for_file 函数，可以在您的模板中使用。此函数返回一个包含贡献者姓名和它们对文件最新提交链接的元组列表。

例如，要基于 Furo 主题在模板中包含贡献者链接，请将类似的代码放置在您的 _templates/footer.html 文件中的适当位置

    {% if display_contributors and pagename and page_source_suffix %}
        {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %}
        {% if contributors %}
          {% if contributors | length > 1 %}
              <a class="display-contributors">Thanks to the {{ contributors |length }} contributors!</a>
          {% else %}
              <a class="display-contributors">Thanks to our contributor!</a>
          {% endif %}
          <div id="overlay"></div>
          <ul class="all-contributors">
              {% for contributor in contributors %}
                  <li>
                      <a href="{{ contributor[1] }}" class="contributor">{{ contributor[0] }}</a>
                  </li>
              {% endfor %}
          </ul>
        {% endif %}
    {% endif %}

有关Sphinx中模板工作方式的信息，请参阅Sphinx文档。

输出样式

该扩展附带一个CSS文件，适用于上面给出的模板示例。您可以根据使用的主题和模板覆盖这些样式或定义自己的样式。