Sostituzioni all'interno dei collegamenti in reST / Sphinx

Question

Sto usando Sphinx per documentare un servizio web che verrà distribuito su server diversi. La documentazione è piena di esempi di URL su cui l'utente può fare clic e dovrebbero semplicemente funzionare. Il mio problema è che l'host, la porta e la radice della distribuzione varieranno e la documentazione dovrà essere rigenerata per ogni distribuzione.

Ho provato a definire sostituzioni come questa:

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

Ma l'HTML generato non è quello che voglio (non include " / percorso " nel link generato):

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

Qualcuno sa come aggirare questo?

Answer 1

Novità in Sphinx v1.0:

sphinx.ext.extlink & # 8211; Markup per abbreviare i collegamenti esterni

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

L'estensione aggiunge un nuovo valore di configurazione:

extlinks

Questo valore di configurazione deve essere un dizionario di siti esterni, che associa nomi alias brevi univoci a un URL di base e un prefisso. Ad esempio, per creare un alias per i problemi sopra menzionati, aggiungere

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

Ora puoi utilizzare il nome alias come nuovo ruolo, ad es. :issue:`123`. Questo quindi inserisce un link a http://bitbucket.org/birkenfeld/sphinx/issue/123. Come puoi vedere, il target indicato nel ruolo viene sostituito nell'URL di base al posto di %s.

La didascalia del collegamento dipende dal secondo elemento della tupla, il prefisso:

Se il prefisso è Nessuno, la didascalia del collegamento è l'URL completo. Se il prefisso è la stringa vuota, la didascalia del collegamento è l'URL parziale indicato nel contenuto del ruolo (123 in questo caso). Se il prefisso è una stringa non vuota, la didascalia del collegamento è l'URL parziale, preceduto dal prefisso & # 8211; nell'esempio sopra, la didascalia del collegamento sarebbe il numero 123. Puoi anche usare il solito & # 8220; titolo esplicito & # 8221; sintassi supportata da altri ruoli che generano collegamenti, ad esempio :issue:`this issue <123>`. In questo caso, il prefisso non è pertinente.

Answer 2

Ok, ecco come l'ho fatto. Innanzitutto, apilinks.py (l'estensione 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)

Ora, in conf.py, aggiungi 'apilinks' all'elenco delle estensioni e imposta un valore appropriato per 'apilinks_base' (altrimenti, per impostazione predefinita sarà 'http://localhost/'). Il mio file è simile al seguente:

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

Utilizzo:

:apilink:`path`

Output:

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

Answer 3

Ho avuto un problema simile in cui dovevo sostituire anche gli URL nei target delle immagini. extlinks non si espande se utilizzato come valore dell'attributo immagine :target:. Alla fine ho scritto una trasformazione sfinge personalizzata che riscrive gli URL che iniziano con un determinato prefisso, nel mio caso http://mybase/. Ecco un codice rilevante per 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

Questo espande la prima fonte seguente in modo da indicare Wikipedia in inglese. Quando conf.py imposta mybase="https://es.wikipedia.org/wiki" i collegamenti rimandano al wiki spagnolo.

* 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

Puoi scrivere una Sfinge estensione che crea un ruolo come

:apilink:`path` 

e genera il collegamento da quello. Non l'ho mai fatto, quindi non posso fare altro che dare questo puntatore, scusa. Dovresti provare a vedere come vengono implementati i vari ruoli. Molti sono molto simili a ciò di cui hai bisogno, credo.