Расширение Sphinx: как я могу настроить текст моих внутренних ссылок Sphinx, используя данные из библиотеки? - PullRequest
Новая
       131

Расширение Sphinx: как я могу настроить текст моих внутренних ссылок Sphinx, используя данные из библиотеки?

0 голосов
/ 12 июля 2020

Немного контекста

В моей библиотеке есть таблица, определяющая ключевые слова, используемые фабрикой для создания объектов. Например: 

class Factory:
    table = {"foo": Foo,
             "bar": Bar}

    def create(key):
        return table[key]()

Конечно, этот пример тривиален, но он предназначен для иллюстрации того, чего я пытаюсь достичь с помощью Sphinx.

Вопрос

Я хочу написать документацию, в которой я могу динамически создавать ссылки, используя фабричный ключ для ссылки на класс. Идея состоит в том, что :factorykey:`foo` должен расширяться до чего-то вроде :class:`foo <Foo>` или (в конце) давать ссылку на расположение документации класса, метка которой будет соответствующим заводским ключом. Как я могу этого добиться?

Что я пробовал

Я черпал вдохновение из этого сообщения и придумал следующий код расширения: 

from docutils import nodes

from somewhere import Factory


def factory_key(name, rawtext, text, lineno, inliner, options={}, content=[]):
    """Link factory key to corresponding class.
    """
    key = text
    cls = Factory.table[key]
    mod = str(cls.__module__)
    name = cls.__name__
    
    node = nodes.Text(text)  # Problem: no link here
    return [node], []


def setup(app):
    app.add_role("factorykey", factory_key)

    return {
        "version": "0.1",
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

Обратите внимание, что это не совсем соответствует тому, что я сказал, что хочу сделать, но я не мог понять, как написать код для новой роли и извлечь выгоду из средств синтаксического анализа RST, которые у меня есть, когда я пишу код для новой директивы. Вместо этого я пытаюсь здесь напрямую создать ссылку на расположение документов класса.

Проблема с моим текущим решением заключается в том, что я не могу понять, как изменить свой код, чтобы создать ссылку на документацию класса . Я пробовал использовать nodes.reference вместо nodes.Text, но не знаю, как получить URI документации класса.

...