Как заставить Sphinx разрешать URL-ссылки из, например, / about-manual в /about-manual.html - PullRequest
Новая
       30

Как заставить Sphinx разрешать URL-ссылки из, например, / about-manual в /about-manual.html

1 голос
/ 21 апреля 2020

Я создаю документацию Sphinx и пытаюсь определить «правильный» способ настройки структуры и ссылок.

СТРУКТУРА 1 #

В настоящее время моя структура выглядит следующим образом: 

index.rst
   about-manual/index.rst

Внутри моего root index.rst, toctree выглядит следующим образом: 

===========================
Contents
===========================

.. toctree::

   about-manual/index

Это приводит к следующим ссылкам: 

https://example.com/docs/             --> Content of index.rst
https://example.com/docs/about-manual --> Content of about-manual/index.rst
  • Это работает как задумано с точки зрения разрешения ссылок
  • Однако я не уверен, является ли это "правильным" способом настройки моей структуры Sphinx

СТРУКТУРА 2 # 

index.rst
about-manual.rst

Внутри моего root index.rst дерево выше, как показано ниже: 

===========================
Contents
===========================

.. toctree::

   about-manual

Это приводит к ссылкам ниже: 

https://example.com/docs/                  --> Content of index.rst
https://example.com/docs/about-manual      --> ERROR
https://example.com/docs/about-manual.html --> Content of about-manual.rst
  • Это приводит к более компактной / простой структуре Sphinx
  • Однако, если пользователь вводит URL без явного .html в конец, ссылка не работает

Мне не хватает базового c параметра конфигурации в Sphinx, чтобы заставить разрешение ссылки работать в соответствии с моими ожиданиями с 'STRUCTURE 2 #' - без добавления явного .html в конце?

И возможно ли избежать того, чтобы документация Sphinx явно разрешалась в index.html в конце пути URL ? Он делает это, как и ожидалось, по индексу root, но в «СТРУКТУРЕ 1 #» все подстраницы явно показывают index.html в конце.

Я смотрел на html_file_suffix и html_link_suffix , но я также не смог заставить их работать в моих целях.

1 Ответ

0 голосов
/ 21 апреля 2020

Я нашел решение для этого, используя sphinx-build -b dirhtml вместо sphinx-build -b html (как предложил Джесси Тан из команды sphinx_rtd_theme) - подробности см. по этой ссылке .

* 1007. * Это в основном позволяет мне использовать подход в 'STRUCTURE 2 #', но он создает вывод с файлами index.html, структурированными в папки, названные в соответствии с файлами .rst.

Важно, что внутренние ссылки также обновляются, чтобы не включать часть index.html.

...