conf.py

# Copyright 2025 bburda
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# 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 matplotlib

matplotlib.use("Agg")
import matplotlib.pyplot as plt

# Ensure readable plots
matplotlib.rcParams["figure.facecolor"] = "white"
matplotlib.rcParams["text.color"] = "black"
matplotlib.rcParams["legend.frameon"] = True
matplotlib.rcParams["legend.framealpha"] = 0.8
matplotlib.rcParams["legend.facecolor"] = "white"
matplotlib.rcParams["legend.edgecolor"] = "gray"
matplotlib.rcParams["figure.autolayout"] = True
matplotlib.rcParams["figure.figsize"] = [10, 6]
matplotlib.rcParams["savefig.bbox"] = "tight"

from datetime import datetime

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "ros2_medkit"
project_copyright = f"{datetime.now().year}, selfpatch"
author = "selfpatch Team"

version = "0.1.0"
release = "0.1.0"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.intersphinx",
    "sphinx_needs",
    "sphinxcontrib.plantuml",
    "sphinx_design",
    "breathe",
    "sphinx_copybutton",
]

# -- Options for Breathe (Doxygen integration) -------------------------------
breathe_projects = {"ros2_medkit": "_build/doxygen/xml"}
breathe_default_project = "ros2_medkit"
breathe_default_members = ("members", "undoc-members")

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]

# The suffix(es) of source filenames
source_suffix = {
    ".rst": "restructuredtext",
}

# The master toctree document
master_doc = "index"

# The language for content autogenerated by Sphinx
language = "en"

# -- Options for Sphinx-Needs ------------------------------------------------
needs_build_json = True
needs_types = [
    dict(
        directive="req",
        title="Requirement",
        prefix="REQ_",
        color="#BFD8D2",
        style="node",
    ),
    dict(
        directive="spec",
        title="Specification",
        prefix="SPEC_",
        color="#FEDCD2",
        style="node",
    ),
    dict(
        directive="impl",
        title="Implementation",
        prefix="IMPL_",
        color="#DF744A",
        style="node",
    ),
    dict(
        directive="test",
        title="Test Case",
        prefix="TEST_",
        color="#DCB239",
        style="node",
    ),
]

needs_links = {
    "links": {
        "incoming": "is linked by",
        "outgoing": "links to",
    },
    "verifies": {
        "incoming": "is verified by",
        "outgoing": "verifies",
        "copy": False,
        "allow_dead_links": False,
    },
}

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]
html_css_files = ["custom.css"]
html_title = f"{project} Documentation"

html_theme_options = {
    "prev_next_buttons_location": "bottom",
    "style_external_links": False,
    "collapse_navigation": False,
    "sticky_navigation": True,
    "navigation_depth": 4,
    "includehidden": True,
    "titles_only": False,
}

# -- Options for intersphinx extension ---------------------------------------
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
}

# -- Options for PlantUML ----------------------------------------------------
plantuml = "java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar"
plantuml_output_format = "svg"

# -- Options for linkcheck ---------------------------------------------------
linkcheck_ignore = [
    r"http://localhost:\d+",  # Ignore localhost URLs
    r"http://127\.0\.0\.1:\d+",
]