feat: build each doc kind with its own MkDocs config and site
This commit is contained in:
@@ -6,17 +6,19 @@ Utilities for working with MkDocs in the doc-forge CLI.
|
||||
---
|
||||
|
||||
Notes:
|
||||
- A single generated `mkdocs.yml` serves lib, api, and wiki content with
|
||||
merged navigation. Wiki navigation, when enabled, precedes every other
|
||||
group and its `index.md` becomes the site `Home`.
|
||||
- A separate `mkdocs.{kind}.yml` configuration and build is emitted per
|
||||
enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and
|
||||
written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).
|
||||
- Navigation blocks are re-rooted per kind: the wiki navigation drops its
|
||||
leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.
|
||||
|
||||
---
|
||||
"""
|
||||
|
||||
import os
|
||||
from collections.abc import Iterable
|
||||
from importlib import resources
|
||||
from pathlib import Path
|
||||
from typing import Any, cast
|
||||
|
||||
import click
|
||||
import yaml
|
||||
@@ -83,53 +85,171 @@ def generate_sources(
|
||||
)
|
||||
|
||||
|
||||
def generate_config(
|
||||
docs_dir: Path,
|
||||
def build_lib_nav(
|
||||
nav_file: Path,
|
||||
template: Path | None,
|
||||
out: Path,
|
||||
site_name: str,
|
||||
modes: Iterable[str] | None = None,
|
||||
site_description: str | None = None,
|
||||
site_author: str | None = None,
|
||||
wiki_dir: Path | None = None,
|
||||
) -> None:
|
||||
docs_root: Path,
|
||||
) -> tuple[list[dict[str, Any]], dict[str, str] | None]:
|
||||
"""
|
||||
Generate an `mkdocs.yml` configuration file.
|
||||
Build the re-rooted navigation block for a lib site.
|
||||
|
||||
The configuration is created by combining a template configuration
|
||||
with a navigation structure derived from the docforge navigation
|
||||
specification (and, when a wiki directory is provided, from the wiki
|
||||
file structure).
|
||||
|
||||
The ``docs_dir`` is always written relative to the MkDocs root and is
|
||||
expected to be the shared documentation parent (for example ``docs``),
|
||||
with generated sources nested under ``lib/`` or ``api/`` subdirectories
|
||||
and hand-written wiki content under a ``wiki/`` subdirectory.
|
||||
The navigation specification is resolved against the shared documentation
|
||||
root and every resulting path is re-rooted relative to the ``lib``
|
||||
subdirectory by stripping its leading ``lib/`` scope component.
|
||||
|
||||
Args:
|
||||
docs_dir (Path):
|
||||
Shared documentation root used as the MkDocs ``docs_dir``.
|
||||
|
||||
nav_file (Path):
|
||||
Path to the `docforge.nav.yml` navigation specification.
|
||||
|
||||
template (Path | None):
|
||||
Optional path to a fully custom MkDocs configuration template.
|
||||
If not provided, built-in templates are merged; the provided
|
||||
template replaces the built-in templates entirely.
|
||||
docs_root (Path):
|
||||
Shared documentation root containing the ``lib`` sources.
|
||||
|
||||
Returns:
|
||||
tuple[list[dict[str, Any]], dict[str, str] | None]:
|
||||
The re-rooted navigation block and the optional theme icon
|
||||
mapping from the specification.
|
||||
|
||||
Raises:
|
||||
click.FileError:
|
||||
If the navigation specification cannot be found.
|
||||
"""
|
||||
if not nav_file.exists():
|
||||
raise click.FileError(str(nav_file), hint="Nav spec not found")
|
||||
|
||||
spec = load_nav_spec(nav_file)
|
||||
resolved = resolve_nav(spec, docs_root)
|
||||
block = MkDocsNavEmitter().emit(resolved)
|
||||
return cast(list[dict[str, Any]], _strip_scope(block, "lib")), spec.icon
|
||||
|
||||
|
||||
def build_wiki_nav_block(wiki_dir: Path) -> list[dict[str, Any]]:
|
||||
"""
|
||||
Build the re-rooted navigation block for a wiki site.
|
||||
|
||||
The wiki navigation derived from the wiki file structure is re-rooted
|
||||
relative to the wiki directory itself by stripping the leading ``wiki/``
|
||||
scope component.
|
||||
|
||||
Args:
|
||||
wiki_dir (Path):
|
||||
Path to the hand-written wiki directory, for example ``docs/wiki``.
|
||||
|
||||
Returns:
|
||||
list[dict[str, Any]]:
|
||||
Navigation entries relative to the wiki directory.
|
||||
|
||||
Raises:
|
||||
click.FileError:
|
||||
If the wiki directory does not exist.
|
||||
"""
|
||||
if not wiki_dir.exists():
|
||||
raise click.FileError(str(wiki_dir), hint="Wiki dir not found")
|
||||
|
||||
return cast(list[dict[str, Any]], _strip_scope(build_wiki_nav(wiki_dir), "wiki"))
|
||||
|
||||
|
||||
def load_spec_icon(nav_file: Path) -> dict[str, str] | None:
|
||||
"""
|
||||
Load the theme icon mapping from a navigation specification.
|
||||
|
||||
Args:
|
||||
nav_file (Path):
|
||||
Path to the navigation specification file.
|
||||
|
||||
Returns:
|
||||
dict[str, str] | None:
|
||||
The icon mapping, or ``None`` when the specification file is
|
||||
absent or cannot be parsed.
|
||||
"""
|
||||
if not nav_file.exists():
|
||||
return None
|
||||
|
||||
try:
|
||||
return load_nav_spec(nav_file).icon
|
||||
except (ValueError, yaml.YAMLError):
|
||||
return None
|
||||
|
||||
|
||||
def _strip_scope(value: object, scope: str) -> object:
|
||||
"""
|
||||
Re-root navigation paths by removing a leading scope component.
|
||||
|
||||
The navigation block is walked recursively and every relative path
|
||||
string that starts with ``{scope}/`` has that prefix removed, so a lib
|
||||
or wiki site scoped to its own ``docs_dir`` can reuse paths that were
|
||||
originally written relative to the shared documentation root.
|
||||
|
||||
Args:
|
||||
value (object):
|
||||
Navigation block, group list, path string, or scalar value.
|
||||
scope (str):
|
||||
Leading path component to strip, for example ``lib`` or ``wiki``.
|
||||
|
||||
Returns:
|
||||
object:
|
||||
The navigation structure with re-rooted paths.
|
||||
"""
|
||||
if isinstance(value, str):
|
||||
prefix = f"{scope}/"
|
||||
return value[len(prefix) :] if value.startswith(prefix) else value
|
||||
if isinstance(value, list):
|
||||
return [_strip_scope(item, scope) for item in value]
|
||||
if isinstance(value, dict):
|
||||
return {key: _strip_scope(val, scope) for key, val in value.items()}
|
||||
return value
|
||||
|
||||
|
||||
def generate_site_config(
|
||||
kind: str,
|
||||
kind_root: Path,
|
||||
nav_block: list[dict[str, Any]],
|
||||
out: Path,
|
||||
site_name: str,
|
||||
docs_dir: str,
|
||||
site_dir: str,
|
||||
template: Path | None = None,
|
||||
site_description: str | None = None,
|
||||
site_author: str | None = None,
|
||||
theme_icon: dict[str, str] | None = None,
|
||||
) -> None:
|
||||
"""
|
||||
Generate a per-kind `mkdocs.{kind}.yml` configuration file.
|
||||
|
||||
The configuration is created by merging the shared ``mkdocs.common.yml``
|
||||
template with the fragment contributed by the kind (``lib``, ``api``, or
|
||||
``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the
|
||||
configuration file's directory: the kind's sources when expressed as a
|
||||
sibling path (for example ``lib``) and the per-kind site output (for
|
||||
example ``../site/lib``).
|
||||
|
||||
Args:
|
||||
kind (str):
|
||||
Documentation kind, one of ``lib``, ``api``, or ``wiki``.
|
||||
|
||||
kind_root (Path):
|
||||
Directory scoped to the kind (for example ``docs/lib``) that
|
||||
serves as the MkDocs ``docs_dir``.
|
||||
|
||||
nav_block (list[dict[str, Any]]):
|
||||
Re-rooted navigation entries for the kind's site.
|
||||
|
||||
out (Path):
|
||||
Destination path where the generated `mkdocs.yml` file will be written.
|
||||
Destination path where the generated ``mkdocs.{kind}.yml`` file
|
||||
is written.
|
||||
|
||||
site_name (str):
|
||||
Display name for the generated documentation site.
|
||||
|
||||
modes (Iterable[str] | None):
|
||||
Documentation modes to enable. Each mode contributes its own
|
||||
built-in template fragment (for example ``lib``, ``api``, or
|
||||
``wiki``), merged on top of the shared ``mkdocs.common.yml``
|
||||
template.
|
||||
docs_dir (str):
|
||||
MkDocs ``docs_dir`` value, relative to the configuration
|
||||
file's directory.
|
||||
|
||||
site_dir (str):
|
||||
MkDocs ``site_dir`` value, relative to the configuration
|
||||
file's directory.
|
||||
|
||||
template (Path | None):
|
||||
Optional path to a fully custom MkDocs configuration template
|
||||
that replaces the built-in templates entirely.
|
||||
|
||||
site_description (str | None):
|
||||
Optional site description written into the configuration.
|
||||
@@ -137,50 +257,26 @@ def generate_config(
|
||||
site_author (str | None):
|
||||
Optional site author written into the configuration.
|
||||
|
||||
wiki_dir (Path | None):
|
||||
Optional path to a hand-written wiki directory (for example
|
||||
``docs/wiki``). When provided, the site navigation is derived
|
||||
from the wiki file structure and placed before the navigation
|
||||
groups defined in ``nav_file``.
|
||||
|
||||
Raises:
|
||||
click.FileError:
|
||||
If the navigation specification, template, or wiki directory
|
||||
cannot be found.
|
||||
theme_icon (dict[str, str] | None):
|
||||
Optional mapping of theme icon entries injected as
|
||||
``theme.icon``.
|
||||
"""
|
||||
if not nav_file.exists() and wiki_dir is None:
|
||||
raise click.FileError(str(nav_file), hint="Nav spec not found")
|
||||
|
||||
nav_block: list[dict] = []
|
||||
if nav_file.exists():
|
||||
spec = load_nav_spec(nav_file)
|
||||
resolved = resolve_nav(spec, docs_dir)
|
||||
nav_block = MkDocsNavEmitter().emit(resolved)
|
||||
else:
|
||||
spec = None
|
||||
|
||||
if wiki_dir is not None:
|
||||
if not wiki_dir.exists():
|
||||
raise click.FileError(str(wiki_dir), hint="Wiki dir not found")
|
||||
wiki_nav = build_wiki_nav(wiki_dir)
|
||||
if wiki_nav:
|
||||
nav_block = wiki_nav + [entry for entry in nav_block if "Home" not in entry]
|
||||
|
||||
data = _load_template(template, modes)
|
||||
data = _load_template(template, [kind])
|
||||
|
||||
data["site_name"] = site_name
|
||||
if site_description:
|
||||
data["site_description"] = site_description
|
||||
if site_author:
|
||||
data["site_author"] = site_author
|
||||
data["docs_dir"] = Path(os.path.relpath(docs_dir, out.parent)).as_posix()
|
||||
data["docs_dir"] = docs_dir
|
||||
data["site_dir"] = site_dir
|
||||
data["nav"] = nav_block
|
||||
|
||||
if spec is not None and spec.icon:
|
||||
if theme_icon:
|
||||
theme = data.setdefault("theme", {})
|
||||
if not isinstance(theme, dict):
|
||||
theme = {}
|
||||
theme["icon"] = spec.icon
|
||||
theme["icon"] = theme_icon
|
||||
data["theme"] = theme
|
||||
|
||||
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
|
||||
@@ -310,28 +406,28 @@ def _deep_merge(base: dict, part: dict) -> dict:
|
||||
return base
|
||||
|
||||
|
||||
def build(mkdocs_yml: Path) -> None:
|
||||
def build_configs(yml_paths: Iterable[Path]) -> None:
|
||||
"""
|
||||
Build the MkDocs documentation site.
|
||||
Build the MkDocs documentation site for every given configuration.
|
||||
|
||||
This function loads the MkDocs configuration and runs the MkDocs
|
||||
build command to generate the final static documentation site.
|
||||
Each configuration file is loaded and built in turn, producing the
|
||||
per-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).
|
||||
|
||||
Args:
|
||||
mkdocs_yml (Path):
|
||||
Path to the `mkdocs.yml` configuration file.
|
||||
yml_paths (Iterable[Path]):
|
||||
Configuration files to build, in order.
|
||||
|
||||
Raises:
|
||||
click.ClickException:
|
||||
If the configuration file does not exist.
|
||||
If a configuration file does not exist.
|
||||
"""
|
||||
if not mkdocs_yml.exists():
|
||||
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
|
||||
|
||||
from mkdocs.commands.build import build as mkdocs_build
|
||||
from mkdocs.config import load_config
|
||||
|
||||
mkdocs_build(load_config(str(mkdocs_yml)))
|
||||
for yml in yml_paths:
|
||||
if not yml.exists():
|
||||
raise click.ClickException(f"mkdocs.yml not found: {yml}")
|
||||
mkdocs_build(load_config(str(yml)))
|
||||
|
||||
|
||||
def serve(mkdocs_yml: Path) -> None:
|
||||
|
||||
Reference in New Issue
Block a user