Внешняя относительная ссылка в директиве Sphinx toctree

Я использую Sphinx для создания моей документации. Я использую другой инструмент для ссылки на API. У меня есть мои документы в каталоге и ссылка API в имени каталога api внутри него.

Я хочу иметь ссылку из документации на ссылку API. Я могу добавить ссылку на ссылку toctree, чтобы:

.. toctree::
   :maxdepth: 1

   starting
   glossary
   main-use-case-flow
   API Reference <http://www.example.com/lib/ios/0.1.0/api/>

Проблема в том, что я не хочу ставить полный путь, я хочу поставить только относительный путь api/

Как я могу поместить ссылку на внешний ресурс, используя относительный путь, а не абсолютный путь?

Ответ 1

Я нашел один из самых опасных способов сделать это. В основном Sphinx позволяет либо путь к документу, либо абсолютный путь, который требует http://. Оказывается, все, что они делают, чтобы проверить вашу ссылку, - это буквально http://.

*WARNING: toctree contains reference to nonexisting document u'downloads'*
Downloads <../downloads>

Но если вы это сделаете:

Downloads <../downloads#http://>

Нет предупреждений! Это означает, однако, что когда пользователь нажимает на вашу ссылку, он вставляет фрагмент http:// или именованный якорь в вашу ссылку на страницу. Если это не допустимый именованный якорь в вашем html, он ничего не сделает на вашей странице (если на вашей странице нет javascript, который делает что-то с именованным якорем).

Ответ 2

Я столкнулся с этой проблемой, когда попытался добавить ссылки на (сгенерированные) javadocs на мой toctree.

Мое решение состояло в создании фальшивого index.rst в соответствующем месте в моем исходном дереве для удовлетворения требований toctree. Я обнаружил, что файл phony index.rst должен содержать заголовок, поэтому мой файл выглядел так:

=======================
Java API (All Packages)
=======================

Когда вы запустите make, этот файл будет скопирован в ваш каталог сборки _build/html (или что-то еще).

И затем просто замените его на реальный файл после обработки reStructuredText.

Ответ 3

В текущей версии Sphinx вы можете просто поставить

.. toctree::

   Title <http://LINK>

и он будет работать.

Ответ 4

Для меня работает следующий синтаксис:

`Page Title <../relative/path.html>`