reST/Sphinx内のリンク内の置換

Question

私は、異なるサーバに配備されるWebサービスを文書化するためにSphinxを使用しています。ドキュメントには、ユーザーがクリックするURLの例がたくさんあります。私の問題は、ホスト、ポート、およびデプロイメントのルートが異なり、すべてのデプロイメントでドキュメンテーションを再生成する必要があるということです。

は、私はこのような置換を定義してみました：

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

ん：

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

をしかし、生成されたHTMLは、私が欲しいものではありません（生成されたリンクでは "/パス" が含まれていません）誰もこの問題を回避する方法を知っていますか？

Answer 1

スフィンクスv1.0をの新機能： - マークアップへ

sphinx.ext.extlinksを私のファイルは次のようになります外部リンクを短くする

extlinks

この設定値は、ベースURLとプレフィックスにユニークな短いエイリアス名をマッピングし、外部サイトの辞書でなければなりません：http://sphinx.pocoo.org/ext/extlinks.html

延長は1つの新しい設定値を追加します。例えば、上述の問題のためのエイリアスを作成するために、あなたは今すぐ

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

を追加し、あなたは、例えば、新しい役割としてエイリアス名を使用することができます:issue:`123`。これにより、http://bitbucket.org/birkenfeld/sphinx/issue/123へのリンクが挿入されます。ご覧のとおり、ロールで指定されたターゲットは、%sの代わりにベースURLに置き換えられます。

リンクのキャプションは、タプルの2番目の項目に依存して、接頭辞：

プレフィックスがNoneの場合は、リンクのキャプションは完全なURLです。 接頭辞が空の文字列の場合、リンクのキャプションはロールの内容（この場合は123）に指定された部分URLです。 接頭辞が空でない文字列の場合、リンクのキャプションは部分URLです。 prefix - 上記の例では、リンクキャプションは123になります。 リンクを生成する他のロールでサポートされている通常の「明示的なタイトル」構文、つまり:issue:`this issue <123>`を使用することもできます。この場合、プレフィックスは関係ありません。

Answer 2

あなたはrole

よう

:apilink:`path` 

を作成し、そこからリンクを生成スフィンクスextensionを書くことができます。私はこれを決してしなかったので、このポインタを与える以外には役に立たない、申し訳ありません。さまざまな役割がどのように実装されているかを見てみるべきです。多くはあなたが必要とするものに非常によく似ています。

Answer 3

ここで私はそれをしました。まず、apilinks.py（スフィンクス拡張子）：

今

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) 

、conf.pyに、（そうでない場合、それは'http://localhost/'がデフォルトになります）拡張子リストに'apilinks'を追加し、'apilinks_base'のための適切な値を設定します。

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

使用法：

:apilink:`path` 

出力：

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