Soru ReST / Sphinx'teki bağlantılar içindeki ikame


Farklı sunucularda dağıtılacak bir web servisini belgelemek için Sphinx kullanıyorum. Doküman, kullanıcının tıklayacağı URL örnekleri ile doludur ve sadece çalışması gerekir. Sorunum, ana makine, bağlantı noktası ve dağıtım kökünün değişeceğidir ve belgelerin her dağıtım için yeniden oluşturulması gerekir.

Bunun gibi tanımlamalar yapmayı denedim:

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

Ancak oluşturulan HTML, istediğim şey değil (oluşturulan bağlantıda "/ yol" ifadesini içermiyor):

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

Bu konuda nasıl çalışılacağını bilen var mı?


18
2017-08-04 11:49


Menşei


Bunun bu soruyla ilgili olup olmadığından emin değilsiniz, ancak şunlar olabilir: stackoverflow.com/a/4836544/2988730. - Mad Physicist


Cevaplar:


Sphinx v1.0'da yeni:

sphinx.ext.extlinks - Harici bağlantıları kısaltmak için işaretleme

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

Uzantı bir yeni yapılandırma değeri ekler:

extlinks

Bu yapılandırma değeri, bir dış URL sözlüğüne ve bir önek ile bir temel URL'ye eşlenik kısa ad isimlerinin eşlenmesidir. Örneğin, yukarıda belirtilen sorunlar için bir takma ad oluşturmak için

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

Şimdi, takma adı yeni bir rol olarak kullanabilirsiniz. :issue:`123`. Bu daha sonra bir bağlantı ekler http://bitbucket.org/birkenfeld/sphinx/issue/123. Gördüğünüz gibi, rolde verilen hedef, temel URL'de yerine %s.

Bağlantı başlığı, tuple'daki ikinci öğeye, öneke bağlıdır:

Önek Hiçbiri değilse, bağlantı başlığı tam URL'dir. Önek boş dize ise, bağlantı başlığı rol içeriğinde verilen kısmi URL'dir (bu durumda 123). Önek boş olmayan bir dize ise, bağlantı başlığı, önek tarafından önceden eklenmiş kısmi URL'dir. Yukarıdaki örnekte, bağlantı başlığı 123 olur. Bağlantı oluşturan diğer roller tarafından desteklenen normal "açık başlık" sözdizimini de kullanabilirsiniz. :issue:`this issue <123>`. Bu durumda, önek uygun değildir.


21
2018-04-27 18:26



Bu Sfenks'e harika bir ektir. Başların için teşekkürler! - Martin Blech
Açıklığı belirtme riskiyle, bunu uzantılarınıza eklemeniz gerekir. conf.py  extensions = ['sphinx.ext.extlinks']. Birisi bulmak zorunda kaldı conf.py bir yolunu bulmak. - ideasman42


Tamam, işte böyle yaptım. İlk, apilinks.py (Sfenks uzantısı):

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)

Şimdi conf.py, eklemek 'apilinks' uzantı listesine ve uygun bir değer 'apilinks_base' (aksi takdirde, varsayılan 'http://localhost/'). Benim dosyam şuna benziyor:

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

Kullanımı:

:apilink:`path`

Çıktı:

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

4
2017-08-05 13:03





Bir Sfenks yazabilirsin uzantı Bu bir oluşturur rol sevmek

:apilink:`path` 

ve bundan bağlantıyı oluşturur. Bunu hiç yapmadım, bu yüzden bu işaretçiyi vermekten daha fazla yardımcı olamam özür dilerim. Çeşitli rollerin nasıl uygulandığına bakmaya çalışmalısınız. Birçoğu ihtiyaç duyduğunuz şeye çok benziyor, bence.


1
2017-08-05 11:28



@thoriann: işaretçiye teşekkürler ve tam uygulamayı görmek için cevabımı kontrol et. - Martin Blech
@martin: cool, şimdi güzel bir örnek var. - tsg