Полное руководство: как убрать index.html из ссылок Sphinx

Чтобы настроить Sphinx так, чтобы исключить index.html из ссылок, но оставить суффиксы .html для остальных файлов, можно использовать параметр конфигурации html_link_suffix в сочетании с пользовательскими шаблонами HTML. Ниже приведено, как это сделать:

Содержание

• Понимание поведения по умолчанию
• Параметры конфигурации
• Решение с пользовательским шаблоном
• Альтернативные подходы
• Шаги реализации
• Ограничения и соображения

Понимание поведения по умолчанию

По умолчанию Sphinx генерирует ссылки с суффиксом .html для всех HTML‑файлов, включая страницы‑индексы. Это приводит к URL‑адресам вида path/to/index.html вместо более чистого path/to/. Согласно документации Sphinx, HTML‑построитель использует html_link_suffix для определения суффикса, используемого в сгенерированных ссылках.

Параметры конфигурации

Основные параметры, влияющие на генерацию ссылок:

• html_file_suffix: управляет фактическим суффиксом имени выходного файла (по умолчанию .html)
• html_link_suffix: управляет суффиксом, используемым в сгенерированных ссылках (по умолчанию совпадает с html_file_suffix)

Вы можете задать их в файле conf.py:

# conf.py
html_file_suffix = '.html'  # сохраняет фактические файлы с расширением .html
html_link_suffix = ''       # убирает .html из ссылок

Однако этот подход удаляет .html из всех ссылок, что может не подойти, если вам нужно сохранить .html для не‑индексных файлов.

Решение с пользовательским шаблоном

Самый точный способ — создать пользовательские шаблоны HTML, которые определяют, когда ссылка указывает на файл‑индекс, и опускают суффикс .html только в этом случае. Вот как это реализовать:

1. Создайте каталог пользовательских шаблонов в вашем проекте:

   _templates/
   

2. Переопределите шаблон linktags.html, чтобы изменить генерацию ссылок:

{# _templates/linktags.html #}
{% macro genrefrole(role, refdoc, refdomain, reftype, target, title=title) %}
  <a class="reference {% if role %}{{ role }}{% endif %}" href="{% if target|lower == 'index' %}{{ pathto(refdoc) }}{% else %}{{ pathto(refdoc) }}{% endif %}">
    {{ title }}
  </a>
{% endmacro %}

3. Или измените шаблон layout.html, чтобы обрабатывать ссылки на индексы:

{# _templates/layout.html #}
{%- if linktype == 'ref' and target|lower == 'index' %}
  <a href="{{ pathto(docname) }}">{{ title }}</a>
{%- else %}
  <a href="{{ pathto(docname) + html_link_suffix }}">{{ title }}</a>
{%- endif %}

Альтернативные подходы

1. JavaScript‑постобработка

Добавьте небольшую JavaScript‑скрипт в вашу документацию, чтобы переписать ссылки index.html после генерации:

// _static/js/rewrite-links.js
document.addEventListener('DOMContentLoaded', function() {
  const links = document.querySelectorAll('a[href$="index.html"]');
  links.forEach(link => {
    link.href = link.href.replace(/index\.html$/, '');
  });
});

Затем подключите этот скрипт в conf.py:

html_static_path = ['_static']
html_js_files = ['js/rewrite-links.js']

2. Создание собственного билдера

Для более тонкого контроля можно создать собственный Sphinx‑билдер, наследующийся от HTML‑билдера и переопределяющий логику генерации ссылок. Это более сложный путь, но он обеспечивает максимальную гибкость.

Шаги реализации

1. Добавьте в ваш conf.py:

# Удалить суффикс .html только из ссылок на index
templates_path = ['_templates']
html_context = {
    'omit_index_html': True,
}

2. Создайте пользовательский шаблон (_templates/linktags.html):

{% macro genrefrole(role, refdoc, refdomain, reftype, target, title=title) %}
  {% set target_lower = target.lower() %}
  {% set link_url = pathto(refdoc) %}
  
  {% if target_lower == 'index' %}
    {% set link_url = link_url[:-5] if link_url.endswith('.html') else link_url %}
  {% endif %}
  
  <a class="reference {% if role %}{{ role }}{% endif %}" href="{{ link_url }}">
    {{ title }}
  </a>
{% endmacro %}

3. Проверьте изменения, пересобрав документацию:

sphinx-build -b html source build

Ограничения и соображения

• Конфигурация сервера: ваш веб‑сервер может потребовать настройки для обслуживания index.html, когда запрашивается каталог.
• Кросс‑ссылки: внутренние кросс‑ссылки в документации могут потребовать корректировки.
• Совместимость с темами: некоторые темы могут переопределять ваши пользовательские шаблоны.
• Поддержка: пользовательские шаблоны могут потребовать обновления при обновлении Sphinx.

Для продакшн‑использования рекомендуется тщательно протестировать, чтобы убедиться, что все ссылки работают корректно на разных страницах и разделах документации. Подход с пользовательским шаблоном даёт наиболее точный контроль над тем, какие ссылки получают суффикс .html.

Источники

1. Документация по конфигурации Sphinx
2. Документация по HTML‑билдеру Sphinx
3. Stack Overflow: решение проблемы суффикса URL в Sphinx
4. Read the Docs Sphinx Theme: проблема с суффиксом URL

Заключение

Чтобы настроить Sphinx так, чтобы исключить index.html из ссылок, но сохранить .html для остальных файлов, у вас есть несколько вариантов:

1. Использовать html_link_suffix = '' — удалит все суффиксы .html (самый простой способ, но затронет все ссылки).
2. Создать пользовательские шаблоны HTML — наиболее точный подход, позволяющий изменить только ссылки на индексы.
3. JavaScript‑постобработка — переписывает ссылки после генерации (минимальные изменения).
4. Рассмотреть использование билдера dirhtml, если вы готовы изменить структуру документации.

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