В Python sphinx, как ссылаться на файл в каталоге _static

У меня есть образцы кода и данных, которые я копирую в каталог _static, и я хотел бы связать эти файлы с документацией, например:

Но проблема в том, что sphinx не создает надлежащую относительную ссылку на этот файл, а просто копирует значения как есть. Поэтому для вложенных файлов, где _static не находится в одном каталоге, ссылки не работают.

Ответы

Ответ 1

То, что вы хотите, это текстовая роль :download:. (как упоминал Митар в своем комментарии).

http://sphinx.pocoo.org/markup/inline.html#role-download

Используя это, вы скажете Sphinx скопировать данный файл в каталог "_downloads" и создать гиперссылку на него. Первоначально это предназначалось для использования в загружаемых файлах, например, в PDF файлах (в html-выходном файле) или в архивах или что-то еще. Он работает отлично для любого другого файла, не являющегося реестром, хотя.

Если вы действительно этого хотели, вы могли бы написать расширение, чтобы сделать это, но я никогда не видел необходимости, так как :download: делает именно то, что я хочу.

Ответ 2

Просто найдите правильный ответ для изображений: предоставьте путь к целевому файлу с помощью /. Для изображений, обозначенных с помощью automodule

.. image:: some_file.png

будет ссылаться на файл some_file.png относительно обрабатываемого файла python, а

.. image:: /some_file.png

будет ссылаться на файл some_file.png относительно местоположения conf.py. Таким образом, нет необходимости загрязнять исходную иерархию изображениями.