bridle

#
# Copyright (c) 2021-2026 TiaC Systems
# Copyright (c) 2021 Li-Pro.Net
#
# SPDX-License-Identifier: Apache-2.0
#
# COPIED and CHANGED from:
# https://github.com/zephyrproject-rtos/zephyr/raw/zephyr-v2.6.0/doc/conf.py
#
# pylint: skip-file
#

import re
import sys
from pathlib import Path

import sphinx

# Paths ------------------------------------------------------------------------

BRIDLE_BASE = Path(__file__).absolute().parents[2]

# Add the '_extensions' directory to sys.path, to enable finding Bridle's
# utilities for Sphinx configuration within.
sys.path.insert(0, str(BRIDLE_BASE / 'doc' / '_utils'))
import utils  # noqa: E402

ZEPHYR_BASE = utils.get_projdir('zephyr')

# Add the '_extensions' directory to sys.path, to enable finding Bridle's
# Sphinx extensions within.
sys.path.insert(0, str(BRIDLE_BASE / 'doc' / '_extensions'))

# Add the 'extensions' directory to sys.path, to enable finding Zephyr's
# Sphinx extensions within.
sys.path.insert(0, str(ZEPHYR_BASE / 'doc' / '_extensions'))

# Project ----------------------------------------------------------------------

# General information about the project.
project = utils.get_projname('devicetree')
copyright = '2015-2026 Zephyr Project and TiaC Systems members and individual contributors'
author = 'The Zephyr Project and TiaC Systems'

# parse version from 'VERSION' file
with open(BRIDLE_BASE / 'VERSION') as f:
    m = re.match(
        (
            r'^VERSION_MAJOR\s*=\s*(\d+)$\n'
            + r'^VERSION_MINOR\s*=\s*(\d+)$\n'
            + r'^PATCHLEVEL\s*=\s*(\d+)$\n'
            + r'^VERSION_TWEAK\s*=\s*(\d+)$\n'
            + r'^EXTRAVERSION\s*=\s*(.*)$'
        ),
        f.read(),
        re.MULTILINE,
    )

    if not m:
        sys.stderr.write('Warning: Could not extract Bridle version.\n')
        version = longversion = 'Unknown'
    else:
        major, minor, patch, tweak, extra = m.groups(1)
        release = version = ".".join((major, minor, patch))
        shortversion = longversion = version
        if tweak:
            longversion += "." + tweak
        if extra:
            version += "-" + extra
            release += "-" + extra

# Overview ---------------------------------------------------------------------

logcfg = sphinx.util.logging.getLogger(__name__)
logcfg.info(project + ' ' + release, color='yellow')
logcfg.info('Build with tags: ' + ':'.join(map(str, tags)), color='red')  # noqa: F821
logcfg.info(f'BRIDLE_BASE is: "{BRIDLE_BASE}"', color='green')
logcfg.info(f'ZEPHYR_BASE is: "{ZEPHYR_BASE}"', color='green')

# General ----------------------------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '8.2'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.extlinks',
    'sphinx.ext.ifconfig',
    'sphinx_tabs.tabs',
    'sphinx_copybutton',
    'notfound.extension',
    'zephyr.dtcompatible-role',
    'zephyr.link-roles',
    'zephyr.kconfig',
    'zephyr.external_content',
    'zephyr.domain',
    'bridle.inventory_builder',
    'bridle.warnings_filter',
]

# Only use SVG converter when it is really needed, e.g. LaTeX.
# pylint: disable=undefined-variable
if tags.has('svgconvert'):  # noqa: F821
    extensions.append('sphinxcontrib.rsvgconverter')

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
source_encoding = 'utf-8-sig'

# Sphinx 2.0 changes the default from 'index' to 'contents'
master_doc = 'index'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# If this is True, todo and todolist produce output, else they produce nothing.
# The default is False.
todo_include_todos = False

# Options for HTML output ------------------------------------------------------

# The theme that the HTML output should use.
html_theme = 'sphinx_tsn_theme'

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = project

# The name of an image file (within the static path) to use as favicon of the
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = f'{BRIDLE_BASE}/doc/_static/images/bridle.ico'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = [f'{BRIDLE_BASE}/doc/_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'

# If false, no module index is generated.
html_domain_indices = False

# If false, no index is generated.
html_use_index = True

# If true, the index is split into individual pages for each letter.
html_split_index = True

# If true, links to the reST sources are added to the pages.
html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
html_show_copyright = True

# If true, license is shown in the HTML footer. Default is True.
html_show_license = True

html_theme_options = {
    'prev_next_buttons_location': None,
    'docsets': utils.get_docsets('devicetree'),
    'default_docset': utils.get_default_docset(),
}

# Options for intersphinx ------------------------------------------------------

intersphinx_mapping = dict()

zephyr_mapping = utils.get_intersphinx_mapping('zephyr')
if zephyr_mapping:
    intersphinx_mapping['zephyr'] = zephyr_mapping

bridle_mapping = utils.get_intersphinx_mapping('bridle')
if bridle_mapping:
    intersphinx_mapping['bridle'] = bridle_mapping

# Options for zephyr.warnings_filter -------------------------------------------

warnings_filter_config = str(BRIDLE_BASE / 'doc' / 'devicetree' / 'known-warnings.txt')
warnings_filter_silent = True

# -- Options for notfound.extension --------------------------------------------

notfound_urls_prefix = '/doc/{}/devicetree/'.format('latest' if version.endswith('99') else version)

# Options for zephyr.external_content ------------------------------------------

# Default directives for included content.
external_content_directives = (
    'figure',
    'image',
    'include',
    'literalinclude',
)
external_content_contents = [
    (BRIDLE_BASE / 'doc' / 'devicetree', '[!_]*'),
]
external_content_keep = [
    'bindings.rst',
    'bindings/**/*',
    'compatibles/**/*',
]


# This function will update the zephyr.warnings_filter setup in case of
# the inventory builder to be more tolerant against missing references.
def update_inventory_warnings_filter_config(app):
    # Check if the value was provided by the original configuration.
    if "warnings_filter_config" in app.config:
        # Update the warnings_filter_config value.
        app.config.warnings_filter_config = str(
            BRIDLE_BASE / 'doc' / 'devicetree' / 'known-warnings-inventory.txt'
        )


def update_config(app):
    # Check if a specific builder was initialized by the user.
    if app.builder.name == "inventory":
        update_inventory_warnings_filter_config(app)

    logcfg.info(f'Warnings filter from: "{app.config.warnings_filter_config}"', color='yellow')


def setup(app):
    app.connect("builder-inited", update_config, 0)
    app.add_css_file('css/common.css')
    app.add_css_file('css/devicetree.css')