doxyfile_init.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/docs/doxyfile_init.py
 
"""
Purpose
-------
Stamp a project's Doxyfile from the bundled template, so that giving a
subproject Doxygen documentation is one command rather than a hand-copied
3,000-line file.
 
The Doxyfile's presence at ``docs/doxygen_work_dir/Doxyfile`` is the whole
declaration: the workspace fan-out builds Doxygen for a subproject only if
that file exists, the docs hub shows a Doxygen card on the same condition,
and ``oct docs --clean`` sweeps its output regardless. Since 2026-09-28 the
workspace manifest's ``html_docs: {"doxygen": false}`` can keep a declared
tier off the docs site (the fan-out skips it and the hub shows no card);
it never puts one there without the file. This module owns that path, so
every consumer agrees on where the declaration lives.
 
Before this module the two Doxyfiles in the workspace were full annotated
copies that had already drifted apart (one still ingested markdown, one had
symlink following on, one lacked three exclusions). The template lists only
the settings that differ from Doxygen's defaults - what ``doxygen -x``
prints - so it fits on a screen and drift is visible in a diff.
 
Responsibilities
----------------
- Own :data:`DOXYFILE_REL`, the one path every consumer resolves.
- :func:`has_doxyfile` - the declaration test.
- :func:`write_doxyfile` - render the template for a project, never
  overwriting an existing file unless told to.
 
Diagnostics
-----------
Domain: OCT-DOCS
Levels:
    L2 - write entry / exit
    L3 - decision (written / kept / overwritten)
    L4 - template resolution
 
Contracts
---------
- Writing is idempotent: an existing Doxyfile is kept and reported, not
  replaced, unless ``force=True``. A project's own edits survive a re-run.
- The only substitution is ``{{PROJECT_NAME}}``. ``INPUT`` is left as a
  placeholder because :mod:`oct.docs.oct_docs` overwrites it at build time,
  which is what keeps the file portable across clones.
- Missing template is an error, not a silent skip: a caller asked for a
  Doxyfile and did not get one.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
from pathlib import Path
 
from oct.core.diagnostics import _dbg
 
 
#: Where a project declares Doxygen, relative to the project root. Every
#: consumer - the single-project build, the workspace fan-out, the hub card
#: filter, the scaffold - resolves this one constant.
DOXYFILE_REL: Path = Path("docs") / "doxygen_work_dir" / "Doxyfile"
 
#: Bundled template, relative to the installed ``oct`` package.
_TEMPLATE_PATH: Path = (
    Path(__file__).resolve().parents[1] / "templates" / "doxygen" / "Doxyfile.template"
)
 
 
class DoxyfileTemplateMissing(FileNotFoundError):
    """The bundled Doxyfile template is not where the package expects it."""
 
 
def has_doxyfile(project_dir: Path) -> bool:
    """Return True when *project_dir* declares Doxygen documentation."""
    return (Path(project_dir) / DOXYFILE_REL).is_file()
 
 
def render_doxyfile(project_name: str) -> str:
    """Return the Doxyfile text for *project_name*.
 
    Raises
    ------
    DoxyfileTemplateMissing
        When the bundled template cannot be read.
    """
    func = "render_doxyfile"
    if not _TEMPLATE_PATH.is_file():
        raise DoxyfileTemplateMissing(
            f"bundled Doxyfile template not found at {_TEMPLATE_PATH}",
        )
    _dbg("OCT-DOCS", func, f"template={_TEMPLATE_PATH}", 4)
    template = _TEMPLATE_PATH.read_text(encoding="utf-8")
    return template.replace("{{PROJECT_NAME}}", project_name)
 
 
def write_doxyfile(
    project_dir: Path,
    project_name: str,
    *,
    force: bool = False,
) -> tuple[Path, bool]:
    """Write the Doxyfile for *project_dir*, creating ``docs/doxygen_work_dir/``.
 
    Parameters
    ----------
    project_dir
        Project root. The file lands at ``project_dir / DOXYFILE_REL``.
    project_name
        Substituted for ``{{PROJECT_NAME}}`` - the title Doxygen shows.
    force
        Overwrite an existing Doxyfile. Off by default so a re-run of
        ``oct scaffold`` or ``oct docs --init-doxygen`` never discards a
        project's own edits.
 
    Returns
    -------
    tuple[Path, bool]
        ``(path, written)``. *written* is False when the file already
        existed and *force* was not given; the existing file is untouched.
 
    Raises
    ------
    DoxyfileTemplateMissing
        When the bundled template is absent.
    """
    func = "write_doxyfile"
    target = Path(project_dir) / DOXYFILE_REL
    _dbg("OCT-DOCS", func, f"target={target} force={force}", 2)
 
    if target.exists() and not force:
        _dbg("OCT-DOCS", func, "exists; kept", 3)
        return target, False
 
    content = render_doxyfile(project_name)
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content, encoding="utf-8")
    _dbg("OCT-DOCS", func, "overwritten" if force else "written", 3)
    return target, True
 
 
__all__ = [
    "DOXYFILE_REL",
    "DoxyfileTemplateMissing",
    "has_doxyfile",
    "render_doxyfile",
    "write_doxyfile",
]