# 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 os
import sys

# -- Path setup --------------------------------------------------------------
# Ensure local source takes priority over any installed version.
# 1. Remove any cached ut_arr imports
for _mod in list(sys.modules):
    if _mod == 'ut_arr' or _mod.startswith('ut_arr.'):
        del sys.modules[_mod]

# 2. Insert project root at the very beginning of sys.path
_project_root = os.path.abspath(os.path.join('..', 'src'))
if _project_root in sys.path:
    sys.path.remove(_project_root)
sys.path.insert(0, _project_root)

# 3. Remove site-packages paths containing ut_arr so they cannot shadow local
import importlib
_local_pkg = os.path.join(_project_root, 'ut_arr')
if os.path.isdir(_local_pkg):
    import ut_arr as _pkg
    _pkg_path = os.path.dirname(_pkg.__file__)
    if os.path.abspath(_pkg_path) != os.path.abspath(_local_pkg):
        # Imported from installed location — force reload from local
        for _mod in list(sys.modules):
            if _mod == 'ut_arr' or _mod.startswith('ut_arr.'):
                del sys.modules[_mod]
        importlib.invalidate_caches()
    del _pkg, _pkg_path
del _local_pkg

# -- Project information -----------------------------------------------------
project = 'ut-arr'
copyright = '2025, Bernd Stroehle'
author = 'Bernd Stroehle'
release = '2.0.0'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.ifconfig',
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '../README.rst']

# Master document
master_doc = 'index'

# Suppress duplicate object warnings (api.rst is canonical, modules/*.rst are summaries)
suppress_warnings = ['duplicate.object']

# -- Options for autodoc -----------------------------------------------------
autodoc_member_order = 'bysource'
autodoc_default_options = {
    'members': True,
    'undoc-members': False,
    'show-inheritance': True,
}

# -- Options for HTML output -------------------------------------------------
# Use RTD theme when available, fall back to alabaster
try:
    import sphinx_rtd_theme  # noqa: F401
    html_theme = 'sphinx_rtd_theme'
    html_theme_options = {
        'navigation_depth': 4,
        'collapse_navigation': False,
    }
except ImportError:
    html_theme = 'alabaster'
    html_theme_options = {
        'description': 'Utilities for Arrays',
        'github_user': '',
        'github_repo': 'ut-arr',
    }

html_static_path = ['_static']

# -- Options for LaTeX / PDF output ------------------------------------------
latex_elements = {
    'papersize': 'a4paper',
    'pointsize': '11pt',
}

latex_documents = [
    ('index', 'ut-arr.tex', 'ut-arr Documentation',
     'Bernd Stroehle', 'manual'),
]

# -- Options for EPUB output -------------------------------------------------
epub_title = project
epub_author = author

# -- Options for DOCX output (via pandoc) ------------------------------------
# Use: make docx  (requires pandoc)

# -- Intersphinx mapping -----------------------------------------------------
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}
