Classes
class	DoxyfileTemplateMissing

Functions
bool	has_doxyfile (Path project_dir)
str	render_doxyfile (str project_name)
tuple[Path, bool]	write_doxyfile (Path project_dir, str project_name, *, bool force=False)

Variables
Path	DOXYFILE_REL = Path("docs") / "doxygen_work_dir" / "Doxyfile"
tuple	_TEMPLATE_PATH

Detailed Description

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)

Function Documentation

◆ has_doxyfile()

bool oct.docs.doxyfile_init.has_doxyfile ( Path project_dir )

Return True when *project_dir* declares Doxygen documentation.

Definition at line 79 of file doxyfile_init.py.

◆ render_doxyfile()

str oct.docs.doxyfile_init.render_doxyfile ( str project_name )

Return the Doxyfile text for *project_name*.

Raises
------
DoxyfileTemplateMissing
    When the bundled template cannot be read.

Definition at line 84 of file doxyfile_init.py.

Here is the caller graph for this function:

◆ write_doxyfile()

tuple[Path, bool] oct.docs.doxyfile_init.write_doxyfile	(	Path	project_dir,
		str	project_name,
		*	,
		bool	force = False )

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.

Definition at line 102 of file doxyfile_init.py.

Here is the call graph for this function:

Variable Documentation

◆ _TEMPLATE_PATH

tuple oct.docs.doxyfile_init._TEMPLATE_PATH

protected

Initial value:

=  (
    Path(__file__).resolve().parents[1] / "templates" / "doxygen" / "Doxyfile.template"
)

Definition at line 70 of file doxyfile_init.py.

◆ DOXYFILE_REL

Path oct.docs.doxyfile_init.DOXYFILE_REL = Path("docs") / "doxygen_work_dir" / "Doxyfile"

Definition at line 67 of file doxyfile_init.py.

Classes

Functions

Variables