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

Question

在我的Sphinx文档实例中，我有：

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

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

• 在我的一些.rst文件中：

  :LaTeXLogo:`LaTeX`
  

但这不起作用，因为make html返回：

警告：未知的解释文本角色"LaTeXLogo"；。

我是不是遗漏了什么？

Answer 1

你必须区分4件事"角色">、"；指令">、"；域">和"；选项">。

标点符号以缩短的语法:role:和.. directive::来区分它们。在完整语法中(不省略域(:domain:role:和.. domain:directive::。最后，"选项">进入"；指令">下的频率较低；角色"，例如：

.. domain:directive::
:option:

或

:domain:role:

那么什么是域呢？大多数时候，它指的是一种编程语言的上下文，该语言具有特定的角色和指令。

话虽如此，让我们来看看所陈述的问题：

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

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

我们立即注意到三件事：

1. 使用的标点符号用于指令，而不是角色
2. 如果检查指令(或角色和域(列表，则没有名为LaTeXLogo的指令
3. 。。。你也不写:role:，因为每个角色都有一个名字(:role:这个词只是用于一般的例子。(

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

在我的一些.rst文件中：

:LaTeXLogo:`LaTeX`

现在我们注意到：

1. 所使用的语法用于角色
2. 在前面的例子中，LaTexLogo是"；指令自变量">
3. 。。。它现在作为一个角色收割

总之，使用上述的唯一情况是"；自定义解释文本角色">，在reStructuredText标记规范中有一个简短的语法描述。如果我们更深入地研究，在reStructuredText解释的文本角色中给出了一般描述，在中给出了更具体的定义；创建重新结构化的文本解释文本角色">，其中存在使用小写的约束：

注册角色

2. 在docutils/parsers/rst/languages/en.py中为角色添加一个条目，将英文名称映射到规范名称(均为小写(

reStructuredText的大多数用户可能不需要这种复杂性。它已经远远超过了初级水平，接近于docutils解析器的DTD定义。如果你最终看到"自定义属性类型">进一步的规范解释了您遇到的错误：

自定义属性类型

在reStructuredText中，可以使用(…(自定义解释文本角色指定自定义类名。Docutils通过标识符规范化将它们规范化，以符合HTML4.1和CSS11.0的名称要求(正则表达式a-z*(。