未知的自定义解释文本角色警告

Question

在我的 Sphinx-doc 实例中，我有：

在我的 conf.py 文件的末尾：

rst_prolog = """
.. role:: LaTeXLogo
"""

在我的一些 .rst 文件中：
```
:LaTeXLogo:`LaTeX`
```

但这行不通，因为 make html returns:

WARNING: Unknown interpreted text role "LaTeXLogo".

我是不是漏掉了什么？

Answer 1

你必须区分 4 个东西“角色”、“指令”、“域” 和 "选项".

标点符号以缩短语法 :role: 和 .. directive:: 区分它们。在完整语法中（不省略域）:domain:role: 和 .. domain:directive::。最后，"options" 在 "directives" 下，较少在 "roles" 下，eg:

.. domain:directive::
    :option:

或

:domain:role:

那么什么是域？大多数情况下，它指的是一种编程语言的上下文 roles and directives specific to it. (Notice the sidebar in the documentation for directives 被划分为域）。

话虽如此，让我们看一下陈述的问题：

at the end of my conf.py file:
rst_prolog = """
.. role:: LaTeXLogo
"""

我们立即注意到三件事：

使用的标点符号用于指示，而不用于角色。
如果您查看 directives (or roles and domains) 的列表，则没有名为 LaTeXLogo...
... 你也不写 :role: 因为每个角色都有一个名字（单词 :role: 仅用于通用示例。）

接下来我们看第二个例子：

in some of my .rst files:
:LaTeXLogo:`LaTeX`

现在我们注意到：

使用的语法是针对角色的。
在前面的示例中，LaTexLogo 是 "directive argument"...
...它现在作为一个角色收割。

总而言之，使用上述内容的唯一情况是 “自定义解释文本角色”，在 reStructuredText Markup Specification. If we dig deeper a general description is given in reStructuredText Interpreted Text Roles, with a more specific definition in "Creating reStructuredText Interpreted Text Roles" 中有一个简短的语法描述，其中一个约束存在关于使用小写字母的问题：

Register the Role

Add an entry to the roles dictionary in docutils/parsers/rst/languages/en.py for the role, mapping the English name to the canonical name (both lowercase).

reStructuredText 的大多数用户可能不需要这种复杂性。它已经远远超过了初学者的水平，并且接近 docutils 解析器的 DTD 定义。如果您最终查看 “自定义属性类型”，进一步的说明会解释您遇到的错误：

Custom attribute types

In reStructuredText, custom class names can be specified using (...) custom interpreted text roles. Docutils normalizes them to conform to both, HTML4.1 and CSS1.0 name requirements (the regular expression a-z*) via the identifier normalization.

未知的自定义解释文本角色警告

Unknown custom interpreted text role warning

restructuredtext

python-sphinx