front_page.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/docs/front_page.py
 
"""
Purpose
-------
Render the workspace-mode docs hub front page. Resolves the template
override at ``<workspace>/docs/_hub/index.html.j2`` and falls back to
the bundled neutral default at ``oct/templates/docs_hub/index.html.j2``.
Substitutes a manifest-driven ``subprojects`` context into the Jinja
template and writes the result to ``<site_root>/index.html``. Also
copies ``<workspace>/assets/`` (if present) into ``<site_root>/_assets/``,
falling back to the bundled defaults bundled under
``oct/templates/docs_hub/_assets/``.
 
Responsibilities
----------------
- Resolve the active template via :func:`resolve_template_path`,
  preferring the workspace override.
- Build the Jinja render context from the loaded
  :class:`oct.core.workspace.Workspace`.
- Render the template and write ``index.html`` to the site root.
- Copy assets from the workspace (or bundled defaults) into the
  site's ``_assets/`` directory.
 
Diagnostics
-----------
Domain: OCT-DOCS
Levels:
    L2 - render entry / exit
    L3 - template resolution decision, asset directory selection
    L4 - per-asset copy
 
Contracts
---------
- Render is pure: same inputs produce the same HTML output (modulo the
  ``generated_at`` ISO timestamp).
- Asset copy uses :func:`shutil.copytree` with ``dirs_exist_ok=True`` -
  no symlinks (Windows safety).
- The renderer never reads or executes user code; the Jinja environment
  has autoescape enabled for HTML safety.
 
Dependencies
------------
- jinja2 (lazy; Environment, FileSystemLoader, select_autoescape - renders the template, already in via Sphinx)
- oct.core.workspace (Workspace dataclass)
- oct.core.diagnostics (_dbg structured logger)
- oct.docs.doxyfile_init (lazy; has_doxyfile - whether a subproject gets a Doxygen card)
- oct.docs.typedoc (lazy; has_typedoc - whether a subproject gets a TypeDoc card)
"""
 
from __future__ import annotations
 
import shutil
from datetime import datetime
from pathlib import Path
from typing import Any
 
from oct.core.diagnostics import _dbg
from oct.core.workspace import Workspace
 
 
#: Bundled-default location relative to the installed ``oct`` package.
_BUNDLED_TEMPLATE_DIR: Path = Path(__file__).resolve().parents[1] / "templates" / "docs_hub"
 
#: Workspace override location relative to a workspace root.
_WORKSPACE_TEMPLATE_REL: Path = Path("docs") / "_hub" / "index.html.j2"
 
#: Workspace asset source relative to a workspace root. When this
#: directory exists, its contents are copied into ``_site/_assets/``.
_WORKSPACE_ASSETS_REL: Path = Path("assets")
 
#: Bundled fallback assets, used only when the workspace has no
#: ``assets/`` directory of its own.
_BUNDLED_ASSETS_DIR: Path = _BUNDLED_TEMPLATE_DIR / "_assets"
 
 
class FrontPageError(Exception):
    """Raised when the front page cannot be rendered."""
 
 
def resolve_template_path(ws_root: Path) -> Path:
    """Return the active front-page template path.
 
    Resolution order:
    1. ``<ws_root>/docs/_hub/index.html.j2`` (workspace override)
    2. ``oct/templates/docs_hub/index.html.j2`` (bundled default)
 
    Raises
    ------
    FrontPageError
        When neither template exists. Should be impossible in normal
        installs because the bundled default ships with the package.
    """
    func = "resolve_template_path"
    override = ws_root / _WORKSPACE_TEMPLATE_REL
    if override.is_file():
        _dbg("OCT-DOCS", func, f"using workspace override: {override}", 3)
        return override
    bundled = _BUNDLED_TEMPLATE_DIR / "index.html.j2"
    if bundled.is_file():
        _dbg("OCT-DOCS", func, f"using bundled default: {bundled}", 3)
        return bundled
    raise FrontPageError(
        f"No front-page template found. Expected either "
        f"{override} (workspace override) or {bundled} (bundled default)."
    )
 
 
def build_render_context(workspace: Workspace) -> dict[str, Any]:
    """Build the Jinja context dict for the front page.
 
    The shape is intentionally narrow so override templates can rely on
    a stable contract:
 
    - ``workspace_name`` -- string, from the manifest
    - ``option_c_href`` -- string, relative URL to the Option C tier
    - ``subprojects`` -- list of dicts ``{"name", "sphinx_href",
      "doxygen_href", "typedoc_href"}``; ``doxygen_href`` is ``None`` for
      a subproject that declares no Doxyfile or whose manifest entry sets
      ``html_docs: {"doxygen": false}``, and ``typedoc_href`` is ``None``
      for one with no ``typedoc.json``; the template shows no card for a
      ``None`` href, and a row left with only its Sphinx card is laid out
      at full width
    - ``generated_at`` -- ISO-8601 timestamp (seconds precision)
 
    Only subprojects the manifest declares as carded appear in
    ``subprojects``: an entry with ``html_docs: false`` has no output to
    link to, and one with ``html_docs: {"hub": false}`` is built and
    reachable by URL but deliberately kept off the index. The template
    therefore does not need to know the manifest schema - it renders
    every entry it is given.
 
    The Doxygen card follows the same declaration the build fan-out uses,
    a Doxyfile at :data:`oct.docs.doxyfile_init.DOXYFILE_REL`. Before
    2026-09-27 every card linked to ``<name>/doxygen/html/index.html``
    unconditionally, which put five dead links on the front page - one per
    subproject that never had a Doxyfile. Since 2026-09-28 the card also
    follows the manifest switch ``html_docs: {"doxygen": false}``, because
    the fan-out then neither builds nor aggregates that subproject's
    Doxygen and a card would point at a withdrawn tree.
    """
    from oct.docs.doxyfile_init import has_doxyfile
    from oct.docs.typedoc import has_typedoc
    return {
        "workspace_name": workspace.name,
        "option_c_href": "option_c/sphinx/html/index.html",
        "subprojects": [
            {
                "name": sp.name,
                "sphinx_href": f"{sp.name}/sphinx/html/index.html",
                "doxygen_href": (
                    f"{sp.name}/doxygen/html/index.html"
                    if sp.html_docs_doxygen and has_doxyfile(sp.path)
                    else None
                ),
                # TypeDoc follows the same rule with its own declaration,
                # typedoc.json: TypeScript subprojects get this card in
                # place of the Doxygen one, since Doxygen cannot parse them.
                "typedoc_href": (
                    f"{sp.name}/typedoc/html/index.html"
                    if has_typedoc(sp.path) else None
                ),
            }
            for sp in workspace.subprojects
            if sp.html_docs and sp.html_docs_hub
        ],
        "generated_at": datetime.now().isoformat(timespec="seconds"),
    }
 
 
def copy_assets(ws_root: Path, site_root: Path) -> Path | None:
    """Copy workspace assets (or bundled fallbacks) into ``site_root/_assets``.
 
    Returns the resolved source directory used, or ``None`` when no
    assets directory was found and nothing was copied.
    """
    func = "copy_assets"
    workspace_assets = ws_root / _WORKSPACE_ASSETS_REL
    target = site_root / "_assets"
 
    if workspace_assets.is_dir():
        _dbg("OCT-DOCS", func, f"copying workspace assets {workspace_assets} -> {target}", 3)
        shutil.copytree(workspace_assets, target, dirs_exist_ok=True)
        return workspace_assets
 
    if _BUNDLED_ASSETS_DIR.is_dir():
        _dbg("OCT-DOCS", func, f"copying bundled assets {_BUNDLED_ASSETS_DIR} -> {target}", 3)
        shutil.copytree(_BUNDLED_ASSETS_DIR, target, dirs_exist_ok=True)
        return _BUNDLED_ASSETS_DIR
 
    _dbg("OCT-DOCS", func, "no asset source found; skipping copy", 3)
    return None
 
 
def render_front_page(ws_root: Path, site_root: Path, workspace: Workspace) -> Path:
    """Render the front page and write it to ``site_root/index.html``.
 
    Parameters
    ----------
    ws_root:
        Workspace root path. Used to find the override template and
        the workspace ``assets/`` directory.
    site_root:
        Aggregation directory (``<ws_root>/_site/`` in normal use).
        Created if it does not exist.
    workspace:
        Loaded :class:`Workspace` providing the manifest data the
        template loops over.
 
    Returns
    -------
    Path
        The absolute path to the written ``index.html``.
    """
    func = "render_front_page"
    _dbg("OCT-DOCS", func, f"start ws_root={ws_root} site_root={site_root}", 2)
 
    site_root.mkdir(parents=True, exist_ok=True)
 
    template_path = resolve_template_path(ws_root)
    context = build_render_context(workspace)
 
    # Defer the Jinja2 import so test environments without it can still
    # exercise the resolution logic above.
    from jinja2 import Environment, FileSystemLoader, select_autoescape
    env = Environment(
        loader=FileSystemLoader(str(template_path.parent)),
        autoescape=select_autoescape(["html", "j2"]),
        keep_trailing_newline=True,
    )
    template = env.get_template(template_path.name)
    html = template.render(**context)
 
    output = site_root / "index.html"
    output.write_text(html, encoding="utf-8")
    _dbg("OCT-DOCS", func, f"wrote {output} ({len(html)} chars)", 3)
 
    copy_assets(ws_root, site_root)
 
    _dbg("OCT-DOCS", func, "end", 2)
    return output
 
 
__all__ = [
    "FrontPageError",
    "resolve_template_path",
    "build_render_context",
    "copy_assets",
    "render_front_page",
]