From 631f357b0e7f926c927a79f224f8806aee5e68a2 Mon Sep 17 00:00:00 2001 From: Xin Han Date: Sun, 16 Aug 2026 19:43:21 +1000 Subject: [PATCH] Generate the API reference from the package Every public estimator needed a one-line stub under docs/api/ and a matching entry in the nav of mkdocs.yml. Seventeen stubs, each holding nothing but a `::: ikpykit.X` directive, and 54 lines of nav. Adding an estimator meant two manual edits, and forgetting either one failed silently: the class simply had no page, with nothing to catch it. The package already states what is public, through the __all__ of each module, so scripts/gen_api_pages.py reads that and writes the pages, the navigation and an overview at build time. What it cannot derive is the section names and their order, which are editorial, so those stay in a list of eight entries. Adding an estimator to a module already in that list now needs no documentation change at all. Six pages change URL, because their names were chosen by hand and no longer match what the class is called: 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 mkdocs-redirects keeps links published against v0.3.0 and earlier working. That map is a fixed list of legacy paths; a new estimator never needs adding to it. Each generated page carries the first paragraph of the class docstring as its description, which fills in the meta description, the social card and the llms.txt entry. Every page had been sharing one generic site description until now, so the cards were identical apart from the title. The hand-written pages get descriptions too. The notebook user guide still falls back to the site description: mkdocs-jupyter does not populate page.meta, so there is nowhere to put one. The four plugins this adds all depend on properdocs, which prints a notice about a possible MkDocs 2.0 on every build. Nothing here acts on it, so the workflows set DISABLE_MKDOCS_2_WARNING to keep the log readable. Co-Authored-By: Claude Opus 5 --- .github/workflows/deploy-gh-pages.yml | 4 + .github/workflows/docs.yml | 5 + docs/README.md | 15 +- docs/api/anomaly/idkd.md | 1 - docs/api/anomaly/iforest.md | 1 - docs/api/anomaly/inne.md | 1 - docs/api/cluster/idkc.md | 1 - docs/api/cluster/ikahc.md | 1 - docs/api/cluster/pskc.md | 1 - docs/api/graph/IsoGraphKernel.md | 1 - docs/api/graph/ikgod.md | 1 - docs/api/group/ikgad.md | 1 - docs/api/kernel/isolation_dis_kernel.md | 1 - docs/api/kernel/isolation_kernel.md | 1 - docs/api/stream/icid.md | 1 - docs/api/stream/streakhc.md | 1 - docs/api/time_series/iktod.md | 1 - docs/api/trajectory/data_loader/sheep_dogs.md | 1 - docs/api/trajectory/ikat.md | 1 - docs/api/trajectory/tidkc.md | 1 - docs/authors/authors.md | 5 + docs/contributing/contribution.md | 5 + docs/examples/examples_english.md | 5 + docs/faq/table-of-contents.md | 5 + docs/quick-start/how-to-install.md | 5 + docs/releases/releases.md | 5 + docs/user_guides/table-of-contents.md | 5 + mkdocs.yml | 57 +++--- pyproject.toml | 4 + scripts/gen_api_pages.py | 179 ++++++++++++++++++ uv.lock | 83 ++++++++ 31 files changed, 350 insertions(+), 49 deletions(-) delete mode 100644 docs/api/anomaly/idkd.md delete mode 100644 docs/api/anomaly/iforest.md delete mode 100644 docs/api/anomaly/inne.md delete mode 100644 docs/api/cluster/idkc.md delete mode 100644 docs/api/cluster/ikahc.md delete mode 100644 docs/api/cluster/pskc.md delete mode 100644 docs/api/graph/IsoGraphKernel.md delete mode 100644 docs/api/graph/ikgod.md delete mode 100644 docs/api/group/ikgad.md delete mode 100644 docs/api/kernel/isolation_dis_kernel.md delete mode 100644 docs/api/kernel/isolation_kernel.md delete mode 100644 docs/api/stream/icid.md delete mode 100644 docs/api/stream/streakhc.md delete mode 100644 docs/api/time_series/iktod.md delete mode 100644 docs/api/trajectory/data_loader/sheep_dogs.md delete mode 100644 docs/api/trajectory/ikat.md delete mode 100644 docs/api/trajectory/tidkc.md create mode 100644 scripts/gen_api_pages.py diff --git a/.github/workflows/deploy-gh-pages.yml b/.github/workflows/deploy-gh-pages.yml index faa554a..7ead0e8 100644 --- a/.github/workflows/deploy-gh-pages.yml +++ b/.github/workflows/deploy-gh-pages.yml @@ -29,6 +29,10 @@ jobs: cancel-in-progress: false permissions: contents: write + env: + # See docs.yml: silences the properdocs notice pulled in by the nav and + # page generation plugins. + DISABLE_MKDOCS_2_WARNING: "true" steps: - uses: actions/checkout@v7 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e35cbf3..34b0dd5 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -10,6 +10,11 @@ permissions: jobs: docs: runs-on: ubuntu-latest + env: + # mkdocs-gen-files, literate-nav, section-index and redirects all depend on + # properdocs, which prints a notice about a possible MkDocs 2.0 on every + # build. Nothing here is acted on by it, so keep it out of the log. + DISABLE_MKDOCS_2_WARNING: "true" steps: - uses: actions/checkout@v7 with: diff --git a/docs/README.md b/docs/README.md index 51f50b6..f24f0ff 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,8 @@ +--- +description: >- + IKPyKit is a scikit-learn compatible Python library implementing Isolation Kernel methods for anomaly detection, clustering and change detection. +--- +