Python Sphinx / rest替换长名称，在同一源文件中定义替换规则

Question

发布Python Sphinx referencing long names提供了一个与我正在寻找的关于长类名替换指令非常接近的答案。

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    .. |ReallyLongExampleClassName| replace:: 
                                    :class:`.ReallyLongExampleClassName`

在提供的示例中，替换规则的定义在同一个pydoc块中。我希望能做到这样的事情：

"""define all rst links/substitutions used in this file
.. |ReallyLongExampleClassName| replace:: :class:`.ReallyLongExampleClassName`
.. |AnotherExampleClassName| replace:: :class:`.AnotherExampleClassName`
"""

# more code
# more code


def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    # define function

由于所讨论的每个文件都是特定的，因此使用rst_epilog并不能很好地扩展。这是否可能。

Answer 1

您可以使用rst_epilog文件中的变量conf.py执行此操作。这是直接从rst_epilog：

获取的

  

rst_epilog

     

一串reStructuredText，它将包含在每个读取的源文件的末尾。这是添加应在每个文件中可用的替换的正确位置。一个例子：

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

但是你说rst_epilog不适合你的用例。也许第一个include directive是更好的方法？您可以将常用的替换文件放入单个第一个文档中，并将其包含在需要使用它们的文档中。