Настройки Sphinx

Настройки Sphinx#

Подавить все warnings подсветки#

suppress_warnings = [
    'misc.highlighting_failure',
    'myst.xref_missing',
]

Настройка для лучшей работы с якорями#

myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
]

Включить автоматическую генерацию якорей для заголовков#

myst_heading_anchors = 3  # Создавать якоря для заголовков до 3 уровня

Вставить оглавление прямо в документ#

# Заголовок документа
```{contents}
:depth: 3
:local:
```

Текст документа...

Или в начале файла:#

# Django

**Содержание:**
```{toctree}
:maxdepth: 2
```

## Установка
## Настройка
## Использование

Глобальная настройка оглавления для всех страниц#

# conf.py
# Автоматически добавлять оглавление на каждую страницу
rst_prolog = """
.. contents:: Содержание
   :depth: 2
   :local:
"""

Для Markdown (через MyST):

myst_enable_extensions = [
    "colon_fence",
    "deflist",
]

# Добавить оглавление автоматически
def setup(app):
    app.connect('source-read', add_toc_to_md)

def add_toc_to_md(app, docname, source):
    if source[0].endswith('.md'):
        toc = "\n```{contents}\n:depth: 2\n:local:\n```\n\n"
        source[0] = toc + source[0]

Добавление pdf-файла#

  ```{eval-rst}
   .. raw:: html
   <iframe src="../_static/pdf/emmet-cheatsheet.pdf" width="100%" height="800px"></iframe>
```

или

<iframe src="../_static/emmet-cheatsheet.pdf" width="100%" height="800px" style="border: none;"></iframe>

<embed src="../_static/emmet-cheatsheet.pdf" type="application/pdf" width="100%" height="800px" />

В теме sphinx_book_theme#

  • убрать кнопки Next…

html_theme = 'sphinx_book_theme'

html_theme_options = {
    "show_prev_next": False,  # Убрать кнопки Previous/Next
}

  • Добавить footer

html_theme_options = {
    "show_prev_next": False,
    
    # Добавить footer
    "extra_footer": """
        <div style="text-align: center; padding: 20px;">
            <p>© 2025 SSV. Все права защищены.</p>
            <p><a href="mailto:email@example.com">Связаться с нами</a></p>
        </div>
    """,
}
Contents