Generate the API reference from the package

[xhan97]

The problem

Every public estimator needed two things written by hand:

1. A stub under docs/api/ holding nothing but a directive — 17 files, each exactly one line:

   docs/api/anomaly/inne.md  →  ::: ikpykit.anomaly.INNE
   

2. An entry in the nav of mkdocs.yml — 54 lines of it.

Forgetting either failed silently. The class just had no page, and nothing caught it.

The change

The package already declares what is public, through the __all__ of each module. scripts/gen_api_pages.py reads that and writes the pages, the navigation and an overview page at build time, via mkdocs-gen-files + mkdocs-literate-nav + mkdocs-section-index.

What it cannot derive is the section names (Point Anomaly Detection, Graph Mining, …) and their order, which are editorial. Those stay, as a list of eight entries. Adding an estimator to a module already in that list now needs no documentation change at all.

Net: docs/api/ (17 files) and 54 lines of nav are gone, replaced by one 179-line generator and a 4-line nav entry.

New: an API overview page

api/index.html is generated too — a table per section listing every estimator with its description. section-index attaches it to the "API Reference" tab, which previously wasn't clickable.

URL changes

Six pages move, because their names were chosen by hand and no longer match the class:

Old	New
api/kernel/isolation_kernel	api/kernel/isokernel
api/kernel/isolation_dis_kernel	api/kernel/isodiskernel
api/graph/IsoGraphKernel	api/graph/isographkernel
api/stream/streakhc	api/stream/streamkhc
api/time_series/iktod	api/timeseries/iktod
api/trajectory/data_loader/sheep_dogs	api/trajectory/dataloader/sheepdogs

The other 11 are unchanged. mkdocs-redirects keeps links published against v0.3.0 and earlier working — verified in the build output, e.g. api/time_series/iktod.html now emits a redirect to ../timeseries/iktod.html. That map is a fixed list of legacy paths; a new estimator never needs adding to it.

Fixing the social cards

Every card was showing the same generic site_description, so 27 cards differed only by title. Each generated page now carries the first paragraph of the class docstring as its description, which feeds the meta description, the social card and the llms.txt entry:

INNE   → "Isolation-based anomaly detection using nearest-neighbor ensembles."
IKGAD  → "Isolation Kernel-based Group Anomaly Detection."

The docstring's first paragraph turned out to be a usable one-liner for all 17 classes. Longer ones are cut at the last sentence that fits in 160 characters, not mid-word.

The 8 hand-written pages got descriptions written for them. One page still falls back to the site description: the notebook user guide, because mkdocs-jupyter does not populate page.meta and there is nowhere to put one.

After: 27 pages, 27 cards, 27 distinct descriptions.

Two things worth knowing

api/SUMMARY.md would have been built as a page. literate-nav reads it and then only marks it not-in-nav, so it still landed in the site, the sitemap and the search index as a bare list of links. The generator sets its inclusion to EXCLUDED; it is an input to the build, not a page.

All four new plugins depend on properdocs, which prints a notice about a possible MkDocs 2.0 on every build. It is by the same author as the plugins and nothing here acts on it, so the workflows set DISABLE_MKDOCS_2_WARNING. Worth flagging since it arrived unannounced with the dependency.

Verification

mkdocs build --strict passes. In the output: 17 class pages at the expected paths, 6 redirect stubs, the overview page, no SUMMARY.html, the nav structure matching the old hand-written one section for section, and llms.txt covering 18 API pages (the 17 plus the overview — the overview needed listing separately, since api/**/*.md only matches pages one directory down).

🤖 Generated with Claude Code