Source code for bundle.docs.config

# Copyright 2026 HorusElohim

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you 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.

from __future__ import annotations

from pathlib import Path

from bundle.core import logger
from bundle.core.data import Data, Field

log = logger.get_logger(__name__)




class DocsConfig(Data):
    """Configuration for a Sphinx documentation build."""

    project_name: str = "TheBundle"
    project_version: str = ""
    author: str = ""
    source_dir: Path = Field(default_factory=Path.cwd)
    output_dir: Path = Field(default_factory=lambda: Path.cwd() / "docs" / "_build" / "html")
    package_dirs: list[str] = Field(default_factory=list)
    autoapi_dirs: list[str] = Field(default_factory=list)
    theme: str = "furo"
    include_readmes: bool = True
    extensions: list[str] = Field(
        default_factory=lambda: [
            "myst_parser",
            "autoapi.extension",
            "sphinx.ext.napoleon",
            "sphinx.ext.viewcode",
            "sphinx.ext.intersphinx",
        ]
    )



    def generate_conf_py(self) -> str:
        """Render a complete Sphinx conf.py as a string."""
        autoapi_dirs_repr = repr([str(d) for d in self.autoapi_dirs])
        extensions_repr = repr(self.extensions)

        return f"""\
# Auto-generated by bundle.docs — do not edit manually

project = {self.project_name!r}
version = {self.project_version!r}
author = {self.author!r}

extensions = {extensions_repr}

# MyST Markdown support
myst_enable_extensions = ["colon_fence", "deflist"]
myst_heading_anchors = 3
source_suffix = {{".rst": "restructuredtext", ".md": "markdown"}}

# sphinx-autoapi — static source analysis (no imports needed)
autoapi_type = "python"
autoapi_dirs = {autoapi_dirs_repr}
autoapi_options = [
    "members",
    "undoc-members",
    "show-inheritance",
    "show-module-summary",
    "imported-members",
]
autoapi_ignore = ["*/_version.py", "*/__pycache__/*"]

# Theme
html_theme = {self.theme!r}
html_title = {self.project_name!r}

# Intersphinx cross-references
intersphinx_mapping = {{
    "python": ("https://docs.python.org/3", None),
    "pydantic": ("https://docs.pydantic.dev/latest/", None),
}}

# Suppress warnings for missing references in auto-generated API docs
suppress_warnings = ["autoapi.python_import_resolution"]
"""