Python Sphinx/замена покоя для длинных имен, определяющих правило замещения в том же исходном файле

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? Вы можете поместить ваши обычно используемые замены в один первый документ и включить его в документы, где вам нужно их использовать.