Sostituzioni all'interno dei collegamenti in reST / Sphinx
-
22-07-2019 - |
Domanda
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?
Soluzione
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.
Altri suggerimenti
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>
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
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.