Substituições dentro ligações em repouso / Sphinx

Question

Eu estou usando Esfinge para documentar um webservice que será implantado em servidores diferentes. A documentação está cheia de exemplos de URL para o usuário a clicar e eles devem funcionar. Meu problema é que o host, porta e raiz de implantação irá variar ea documentação terá de ser para cada implementação gerado-re.

Eu tentei definindo substituições assim:

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

Mas o HTML gerado não é o que eu quero (não inclui "/ path" no link gerado):

<a href="http://localhost:8080">http://localhost:8080</a>/path

Alguém sabe como resolver isso?

Answer 1

Novo em Esfinge v1.0:

sphinx.ext.extlinks - Markup para encurtar links externos

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

A extensão adiciona um novo valor de configuração:

extlinks

Este valor de configuração deve ser um dicionário de sites externos, mapeando nomes curto alias exclusivo a um URL de base e um prefixo. Por exemplo, para criar um alias para as questões acima mencionadas, você adicionaria

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

Agora, você pode usar o nome do alias como um novo papel, por exemplo, :issue:`123`. Este, em seguida, insere um link para http://bitbucket.org/birkenfeld/sphinx/issue/123. Como você pode ver, o alvo dada no papel é substituído na URL base no lugar de %s.

A legenda ligação depende do segundo item na tupla, o prefixo:

Se o prefixo é Nenhum, a legenda da ligação é a URL completa. Se o prefixo é a cadeia vazia, a legenda da ligação é o URL parcial dada no conteúdo papel (123 neste caso). Se o prefixo é uma cadeia não-vazia, a legenda da ligação é o URL parcial, prefixado pelo prefixo - no exemplo acima, o subtítulo ligação seria emissão 123. Você também pode usar o habitual sintaxe “título explícito” apoiado por outros papéis que geram links, ou seja :issue:`this issue <123>`. Neste caso, o prefixo não é relevante.

Answer 2

Ok, aqui está como eu fiz isso. Primeiro, apilinks.py (a extensão 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)

Agora, em conf.py, adicione 'apilinks' à lista de extensões e definir um valor apropriado para 'apilinks_base' (caso contrário, ele será o padrão para 'http://localhost/'). Meus arquivo se parece com isso:

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

Uso:

:apilink:`path`

Output:

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

Answer 3

Eu tive um problema semelhante onde eu precisava para substituir também URLs em alvos de imagem. O extlinks não se expandem quando usado como um valor de atributo de imagem :target:. Eventualmente, eu escrevi uma transformação esfinge personalizado que reescreve URLs que começam com um determinado prefixo, no meu caso, http://mybase/. Aqui está um código relevante para conf.py:

from sphinx.transforms import SphinxTransform

class ReplaceMyBase(SphinxTransform):

    default_priority = 750
    prefix = 'http://mybase/'

    def apply(self):
        from docutils.nodes import reference, Text
        baseref = lambda o: (
            isinstance(o, reference) and
            o.get('refuri', '').startswith(self.prefix))
        basetext = lambda o: (
            isinstance(o, Text) and o.startswith(self.prefix))
        base = self.config.mybase.rstrip('/') + '/'
        for node in self.document.traverse(baseref):
            target = node['refuri'].replace(self.prefix, base, 1)
            node.replace_attr('refuri', target)
            for t in node.traverse(basetext):
                t1 = Text(t.replace(self.prefix, base, 1), t.rawsource)
                t.parent.replace(t, t1)
        return

# end of class

def setup(app):
    app.add_config_value('mybase', 'https://en.wikipedia.org/wiki', 'env')
    app.add_transform(ReplaceMyBase)
    return

Isso expande a seguinte fonte primeira para apontar para Inglês wikipedia. Quando conjuntos conf.py mybase="https://es.wikipedia.org/wiki" as ligações que apontam para a wiki em espanhol.

* inline link http://mybase/Helianthus
* `link with text <http://mybase/Helianthus>`_
* `link with separate definition`_
* image link |flowerimage|

.. _link with separate definition: http://mybase/Helianthus

.. |flowerimage| image:: https://upload.wikimedia.org/wikipedia/commons/f/f1/Tournesol.png
   :target: http://mybase/Helianthus

Answer 4

Você pode escrever uma esfinge extensão que cria um papel como

:apilink:`path` 

e gera o link a partir daí. Eu nunca fiz isso, então eu não posso ajudar mais do que dar este ponteiro, desculpe. Você deve tentar olhar para como as várias funções são implementadas. Muitos são muito parecido com o que você precisa, eu acho.