ReST/Sphinx'teki bağlantılar içindeki değiştirmeler

Question

Farklı sunucularda dağıtılacak bir web hizmetini 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.

böyle değiştirmelerin tanımlayan çalıştı:

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

mu:

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

Ama oluşturulan HTML ne istiyorum değil (oluşturulan bağlantı "/ yolu" içermez) Herkes bu konuda nasıl çalışacaklarını biliyor mu?

Answer 1

Yeni Sfenks 1.0 sürümündeki:

sphinx.ext.extlinks - İşaretleme için harici bağlantıları kısaltın

extlinks

Bu yapılandırma değeri temel URL ve bir önek özgü kısa takma adlar haritalama, dış sitelerin bir sözlük olması gerekir:http://sphinx.pocoo.org/ext/extlinks.html

uzatma yeni bir yapılandırma değer katar. Örneğin, örneğin yeni bir role olarak takma adı kullanabilirsiniz Asistan

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

eklersiniz, yukarıda bahsi geçen olaylar bir takma ad oluşturmak için :issue:`123`. Bu daha sonra http://bitbucket.org/birkenfeld/sphinx/issue/123'a bir bağlantı ekler. Gördüğünüz gibi, rolde verilen hedef, %s yerine temel URL'de değiştirilir.

bağlantı başlık başlığın ikinci öğeye bağlıdır, önek:

önek Yok ise, bağlantı başlık tam bir URL. Ö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ığı kısmi URL'dir. önek - yukarıdaki örnekte, bağlantı başlığı 123 olur. Ayrıca, bağlantı oluşturan diğer rollerin, yani :issue:`this issue <123>`, tarafından desteklenen olağan "açık başlık" sözdizimini de kullanabilirsiniz. Bu durumda, önek uygun değildir.

Answer 2

Bir role

gibi

:apilink:`path` 

oluşturur ve bu bağlantıyı oluşturan bir Sfenks extension yazabilirsiniz. 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.

Answer 3

Tamam, işte nasıl yaptım. Birincisi, 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 yılında, uzantılar listesine 'apilinks' ekleyip 'apilinks_base' için uygun bir değer (aksi takdirde 'http://localhost/' varsayılan değer olur) ayarlayın. Dosyam şöyle görünür:

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>