reST / Sphinxのリンク内の置換

Question

Sphinxを使用して、異なるサーバーにデプロイされるWebサービスを文書化します。ドキュメントには、ユーザーがクリックするためのURLの例がたくさんあり、それらは動作するはずです。私の問題は、ホスト、ポート、展開ルートが異なるため、展開ごとにドキュメントを再生成する必要があることです。

次のような置換を定義しようとしました：

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

しかし、生成されたHTMLは私が望むものではありません（生成されたリンクに<！> quot; / path <！> quot;を含めないでください）：

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

これを回避する方法を知っている人はいますか

Answer 1

Sphinx v1.0の新機能：

sphinx.ext.extlinks <！>＃8211;外部リンクを短くするためのマークアップ

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

拡張機能は1つの新しい設定値を追加します：

拡張リンク

この設定値は、一意の短いエイリアス名をベースURLとプレフィックスにマッピングする外部サイトの辞書でなければなりません。たとえば、上記の問題のエイリアスを作成するには、追加します

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です。 プレフィックスが空でない文字列の場合、リンクキャプションは、プレフィックス<！>＃8211が先頭に追加された部分URLです。上記の例では、リンクのキャプションは問題123です。 通常の<！>＃8220; explicit title <！>＃8221;も使用できます。リンクを生成する他のロールでサポートされる構文、つまり:issue:`this issue <123>`。この場合、接頭辞は関係ありません。

Answer 2

わかりました、これが私がやった方法です。まず、apilinks.py（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)

今、conf.pyで、拡張リストに'apilinks'を追加し、'apilinks_base'に適切な値を設定します（それ以外の場合、デフォルトは'http://localhost/'になります）。私のファイルは次のようになります。

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>

Answer 3

同様の問題があり、画像ターゲットのURLも置き換える必要がありました。 extlinksは、イメージの:target:属性の値として使用されたときに展開されません。 最終的に、特定のプレフィックス（私の場合はhttp://mybase/）で始まるURLを書き換えるカスタムスフィンクス変換を作成しました。 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

これにより、次の最初のソースが英語版ウィキペディアを指すように展開されます。 conf.pyがmybase="https://es.wikipedia.org/wiki"を設定すると、リンクはスペイン語のウィキを指します。

* 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

拡張を作成できます/sphinx.pocoo.org/markup/inline.html "rel =" nofollow noreferrer ">役割のような

:apilink:`path` 

そしてそれからリンクを生成します。私はこれを一度もしなかったので、このポインタを与えること以上に仕方がありません、ごめんなさい。さまざまな役割がどのように実装されているかを確認する必要があります。多くはあなたが必要とするものに非常に似ていると思います。