Замены внутри ссылок в reST/Sphinx

Я использую Sphinx для документирования веб-сервиса, который будет развернут на разных серверах. Документация заполнена примерами URL-адресов, которые пользователь может щелкнуть, и они должны просто работать. Моя проблема заключается в том, что корень хоста, порта и развертывания будет отличаться, и документация должна быть сгенерирована для каждого развертывания.

Я попытался определить такие подстановки следующим образом:

|base_url|/path
.. |base_url| replace:: http://localhost:8080

Но сгенерированный HTML не то, что я хочу (не содержит "/path" в сгенерированной ссылке):

<a href="#" onclick="location.href='http://localhost:8080'; return false;">http://localhost:8080</a>/path

Кто-нибудь знает, как обойти это?

Ответы

Ответ 1

Новое в Sphinx v1.0:

sphinx.ext.extlinks - Разметка для сокращения внешних ссылок

http://sphinx.pocoo.org/ext/extlinks.html

Расширение добавляет одно новое значение конфигурации:

extlinks

Это значение конфигурации должно быть словарем внешних сайтов, сопоставляя уникальные короткие псевдонимы с базовым URL-адресом и префиксом. Например, чтобы создать псевдоним для вышеупомянутых проблем, вы должны добавить

extlinks = {'issue': 
    ('http://bitbucket.org/birkenfeld/sphinx/issue/%s', 'issue ')}

Теперь вы можете использовать имя псевдонима в качестве новой роли, например. :issue:`123`. Затем вставляется ссылка на http://bitbucket.org/birkenfeld/sphinx/issue/123. Как вы можете видеть, цель, указанная в роли, заменяется в базовом URL-адресе вместо %s.

Заголовок ссылки зависит от второго элемента в кортеже, префикса:

Если префикс равен None, заголовок ссылки - полный URL. Если префикс является пустой строкой, заголовок ссылки - это частичный URL-адрес, указанный в содержании роли (в этом случае 123). Если префикс является непустой строкой, заголовок ссылки является частичным URL-адресом, добавленным префиксом - в приведенном выше примере заголовок ссылки будет выпуском 123. Вы также можете использовать обычный синтаксис "явного заголовка", поддерживаемый другими ролями, которые генерируют ссылки, т.е. :issue:`this issue <123>`. В этом случае префикс не имеет значения.

Ответ 2

Хорошо, вот как я это сделал. Во-первых, apilinks.py (расширение Sphinx):

from docutils import nodes, utils

def setup(app):
    def api_link_role(role, rawtext, text, lineno, inliner, options={},
                      content=[]):
        ref = app.config.apilinks_base + text
        node = nodes.reference(rawtext, utils.unescape(ref), refuri=ref,
                               **options)
        return [node], []
    app.add_config_value('apilinks_base', 'http://localhost/', False)
    app.add_role('apilink', api_link_role)

Теперь в conf.py добавьте 'apilinks' в список расширений и установите соответствующее значение для 'apilinks_base' (в противном случае по умолчанию будет 'http://localhost/'). Мой файл выглядит следующим образом:

extensions = ['sphinx.ext.autodoc', 'apilinks']
# lots of other stuff
apilinks_base = 'http://host:88/base/'

Использование:

:apilink:`path`

Вывод:

<a href="http://host:88/base/path">http://host:88/base/path</a>

Ответ 3

Вы можете написать Sphinx extension, который создает роль, например

:apilink:`path`

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