23

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

私はこのような置換を定義しようとしました:

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

しかし、生成された HTML は私が望むものではありません (生成されたリンクに「/path」が含まれていません):

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

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

4

4 に答える 4

30

Sphinx v1.0 の新機能:

sphinx.ext.extlinks – 外部リンクを短縮するためのマークアップ

https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

この拡張機能は、1 つの新しい構成値を追加します。

外部リンク

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

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

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

リンクのキャプションは、タプルの 2 番目の項目であるプレフィックスに依存します。

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

于 2011-04-27T18:26:10.590 に答える
4

わかりました、これが私がやった方法です。まず、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>
于 2009-08-05T13:03:10.750 に答える
1

次のようなロールを作成するSphinx拡張機能を作成できます。

:apilink:`path`

そこからリンクを生成します。私はこれをやったことがないので、このポインターを提供する以上のことはできません。申し訳ありません。さまざまな役割がどのように実装されているかを調べてみてください。多くはあなたが必要とするものと非常に似ていると思います。

于 2009-08-05T11:28:34.940 に答える