Попросите Sphinx заменить текст строки документации

Я документирую код в Sphinx, который похож на этот:

class ParentClass(object):
    
    def __init__(self):
        pass

    def generic_fun(self):
        """Call this function using /run/ParentClass/generic_fun()"""
        do_stuff()

class ChildClass(ParentClass):
    
    def specific_fun(self):
        """Call this function using /run/ChildClass/specific_fun()"""
        do_other_stuff()

Я добавил :inherited-members в документацию ChildClass, поэтому у меня там есть операторы вроде Вызов этой функции с помощью /run/ParentClass/generic_fun().

Есть ли способ поместить что-то в строки документации, например ‹class_name›, которые Sphinx заменит фактическим классом, который он документирует?

Я хотел бы, чтобы код выглядел так:

class ParentClass(object):
    
    def __init__(self):
        pass

    def generic_fun(self):
        """Call this function using /run/<class_name>/generic_fun()"""
        do_stuff()

Таким образом, в разделе ChildClass документация Sphinx будет читать (...), используя /run/ChildClass/generic_fun()(...), а раздел ParentClass будет читать (...), используя /run/ParentClass/generic_fun(). (...)?

В идеале я хотел бы иметь документацию на одной странице, поэтому строка замены была бы разной для разных разделов.


python substitution python-sphinx docstring
person Charles L.    schedule 28.07.2012    source источник

Ответы (1)


arrow_upward
8
arrow_downward

Я нашел способ сделать это, глядя на что-то еще.

Есть функции, которые autodoc будет вызывать перед печатью сообщения. Я добавил этот код в свой файл conf.py:

def get_class_name(full_module_name):
    """
    Pull out the class name from the full_module_name
    """
    #split the full_module_name by "."'s
    return full_module_name.split('.')[-1]

def process_docstring(app, what, name, obj, options, lines):
    classname = get_class_name(name)

    # loop through each line in the docstring and replace |class| with
    # the classname
    for i in xrange(len(lines)):
        lines[i] = lines[i].replace('|class|', classname)

def setup(app):
    app.connect('autodoc-process-docstring', process_docstring)

Я хочу использовать | token, но они зарезервированы для глобальных замен. Я обошел это, поместив следующую строку в свой первый файл (поэтому код заменяет |class| на |class|):

.. |class| replace:: `|class|`
person Charles L.    schedule 31.07.2012