docs/source/conf.py - master - Ulyanoff/mlops1

docs/source/conf.py
130 строк4 KB
Artem Ivochkin
todo со ссылками на модуль с кодом
11 янв 2026, 18:45
11 янв 2026, 18:453ad959e
# Configuration file for the Sphinx documentation builder.
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import sys, os
from pathlib import Path

project_root = Path(__file__).parents[2].resolve()  # корень проекта
src_path = project_root / 'src'  # код проекта
sys.path.insert(0, str(src_path))
print(f'Код проекта: {sys.path[0]}')

sys.path.insert(0, str(Path(__file__).parent))
from todos import com_generate_todos

# -- Project information -----------------------------------------------------
project = 'Шаблон продуктивизации'
from datetime import date

copyright = f'2025-{date.today().year}, Отдел продуктивизации'
author = 'A.M.Ulyanoff'
release = '0.1.0'

language = 'ru'

# html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    'navigation_depth': 4,
    'collapse_navigation': False,
    'titles_only': False,
    'logo_only': False,
    # 'display_version': True,
    'style_external_links': True,
}

# Логотип и иконка
html_logo = '_static/vtb_logo_ru_300x172.png'
html_favicon = '_static/vtb_favicon.ico'

extensions = [
    # Основные расширения Sphinx
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx',
    'sphinx.ext.autosummary',
    'sphinx.ext.graphviz',
    'sphinx.ext.todo',
    'sphinx.ext.mathjax',

    # сваггер
    'sphinxcontrib.openapi',

    # Дополнительные расширения
    # 'sphinx_autodoc_typehints',
    'myst_parser',
    'sphinx_copybutton',
    'sphinx_design',
    # 'sphinxcontrib.mermaid',
]

# Настройки расширений
myst_enable_extensions = [
    'dollarmath',
    'amsmath',
    'deflist',
    'fieldlist',
    'html_admonition',
    'html_image',
    'colon_fence',
    'smartquotes',
    'replacements',
    # 'linkify',
    'substitution',
]
autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__',
    'show-inheritance': True,
}
nitpicky = False  # Отключает строгую проверку ссылок
# Или игнорируем конкретные метки
# nitpick_ignore = [
#     ('py:class', 'sqlalchemy.orm.Mapper'),
#     ('py:class', 'sqlalchemy.sql.expression.SQLCoreOperations'),
# ]
autosummary_generate = True
autosummary_generate_overwrite = False
autosummary_imported_members = True
autoclass_content = 'both'
napoleon_google_docstring = True
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = True
napoleon_include_private_with_doc = False
todo_include_todos = True

# Поддержка Markdown и reStructuredText
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

html_static_path = ['_static']
html_css_files = ['custom.css']
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']  # Исключаемые шаблоны

# ======================================================================================================================
# Собираем TODO-комментарии по коду
# ======================================================================================================================

def setup(app):
    """Точка входа для Sphinx.
    Sphinx автоматически вызывает функцию setup(app) из любого расширения (включая conf.py), если она определена.
    Регистрируем обработку события builder-inited. Каждый раз, когда Sphinx начинает сборку документации
    (make html, sphinx-build и т.д.), он сначала инициализирует билдер → и сразу вызывает нашу generate_todos.
    В этот момент:
        - файловая система доступна;
        - можно читать исходники;
        - можно генерировать .rst-файлы до того, как Sphinx начнёт их обрабатывать.
    """
    app.connect('builder-inited', com_generate_todos)
    return {'version': str(release), 'parallel_read_safe': True}

if __name__ == '__main__':
    com_generate_todos('app')