Skip to content

update-template-docs-autodoc - #13

Merged
jreakin merged 5 commits into
mainfrom
update-template-docs-autodoc
May 8, 2026
Merged

jreakin merged 5 commits into
mainfrom
update-template-docs-autodoc

Conversation

@jreakin

@jreakin jreakin commented May 8, 2026 •

Copy link
Copy Markdown
Member

Summary- Updated template documentation and added autodoc and skill mirrors- Added TypeScript autod targets and updated setup skill Added abstract-data docs-author skill- Improved automated logo detection and configuration edits- Implemented prose-inventory and thin-page postprocessing for docs

Summary by CodeRabbit

  • New Features

    • Added TypeScript API documentation auto-generation alongside existing Python support
    • Introduced GitHub Pages deployment workflow for live documentation demos
    • Enhanced setup wizard with multi-stack detection (Python, TypeScript, Next.js, TanStack, etc.)
    • Added documentation enrichment skill for writing narrative guides and examples
  • Chores

    • Updated dependency version synchronization automation
    • Improved template scaffolding with enriched quickstart and landing page content
    • Added smoke testing for publish pipeline validation
    • Updated Git configuration for Bun lockfile management

* bun add -d typedoc typedoc-plugin-markdown
*/
import { execSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
log('');
log(`${c.dim}→ post-processing thin pages${c.reset}`);

const documentedSet = new Set(pages.map((p) => p.mod));
* bun add -d typedoc typedoc-plugin-markdown
*/
import { execSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
log('');
log(`${c.dim}→ post-processing thin pages${c.reset}`);

const documentedSet = new Set(pages.map((p) => p.mod));
Comment thread scripts/smoke-test.mjs
*
* which also verifies `bun create @abstractdata/docs` works against npm.
*/
import { existsSync, mkdtempSync, readdirSync, readFileSync, statSync, rmSync } from 'node:fs';
* bun add -d typedoc typedoc-plugin-markdown
*/
import { execSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
log('');
log(`${c.dim}→ post-processing thin pages${c.reset}`);

const documentedSet = new Set(pages.map((p) => p.mod));
Comment thread scripts/compile-skill.mjs
}

// Per-skill (mirror + cursor)
for (const [key, skill] of Object.entries(skillData)) {
@coderabbitai

coderabbitai Bot commented May 8, 2026 •

Copy link
Copy Markdown

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 15334262-a587-4d82-a7cc-8aa2baa2094b

📥 Commits

Reviewing files that changed from the base of the PR and between a760a04 and 6e03fdc.

⛔ Files ignored due to path filters (1)
  • bun.lock is excluded by !**/*.lock
📒 Files selected for processing (49)
  • .claude/skills/abstract-data-docs-author/SKILL.md
  • .claude/skills/abstract-data-setup/SKILL.md
  • .cursor/rules/abstract-data-docs-author.mdc
  • .cursor/rules/abstract-data-setup.mdc
  • .github/copilot-instructions.md
  • .github/workflows/deploy-playground.yml
  • .gitignore
  • README.md
  • apps/playground/astro.config.mjs
  • apps/playground/scripts/build-python-docs.mjs
  • apps/playground/scripts/build-ts-docs.mjs
  • apps/playground/scripts/python-autodoc.json
  • apps/playground/scripts/ts-autodoc.json
  • apps/playground/src/content/docs/api/auditkit.md
  • apps/playground/src/content/docs/api/example_module.md
  • apps/playground/src/content/docs/api/index.md
  • package.json
  • packages/create-docs/bin/cli.js
  • packages/create-docs/package.json
  • packages/starlight-theme/bin/install-skills.js
  • packages/starlight-theme/package.json
  • packages/starlight-theme/scripts/build-python-docs.mjs
  • packages/starlight-theme/scripts/build-ts-docs.mjs
  • packages/starlight-theme/scripts/python-autodoc.json
  • packages/starlight-theme/scripts/ts-autodoc.json
  • packages/starlight-theme/skills/claude/CLAUDE.md
  • packages/starlight-theme/skills/claude/abstract-data-docs-author/SKILL.md
  • packages/starlight-theme/skills/claude/abstract-data-setup/SKILL.md
  • packages/starlight-theme/skills/cursor/abstract-data-docs-author.mdc
  • packages/starlight-theme/skills/cursor/abstract-data-setup.mdc
  • packages/starlight-theme/skills/cursor/welcome.mdc
  • packages/starlight-theme/skills/github/copilot-instructions.md
  • packages/template/.claude/skills/abstract-data-docs-author/SKILL.md
  • packages/template/.claude/skills/abstract-data-setup/SKILL.md
  • packages/template/.cursor/rules/abstract-data-docs-author.mdc
  • packages/template/.cursor/rules/abstract-data-setup.mdc
  • packages/template/.cursor/rules/welcome.mdc
  • packages/template/.github/copilot-instructions.md
  • packages/template/.gitignore
  • packages/template/CLAUDE.md
  • packages/template/scripts/build-python-docs.mjs
  • packages/template/scripts/build-ts-docs.mjs
  • packages/template/scripts/python-autodoc.json
  • packages/template/scripts/ts-autodoc.json
  • packages/template/src/content/docs/index.mdx
  • packages/template/src/content/docs/quickstart.md
  • scripts/compile-skill.mjs
  • scripts/smoke-test.mjs
  • scripts/sync-theme-version.mjs

Walkthrough

This PR expands the Abstract Data Documentation Theme from a Python-only setup tool into a multi-stack, AI-powered documentation platform. It adds TypeScript autodoc generation alongside Python, introduces two companion AI skills (setup and docs enrichment) with Claude, Cursor, and Copilot procedural rules, refactors the skill compiler to support multiple skills, implements end-to-end testing, and updates project scaffolding with expanded configuration workflows.

Changes

Multi-Stack Autodoc Generators

Layer / File(s) Summary
Configuration Schemas
apps/playground/scripts/ts-autodoc.json, packages/starlight-theme/scripts/ts-autodoc.json, packages/template/scripts/ts-autodoc.json, apps/playground/scripts/python-autodoc.json, packages/starlight-theme/scripts/python-autodoc.json, packages/template/scripts/python-autodoc.json
JSON configuration files defining entry points, output directories, repository metadata, and generation settings for both Python and TypeScript autodoc pipelines.
TypeScript Autodoc Script
apps/playground/scripts/build-ts-docs.mjs, packages/starlight-theme/scripts/build-ts-docs.mjs, packages/template/scripts/build-ts-docs.mjs
Node.js CLI that runs TypeDoc with markdown plugin, extracts titles and descriptions from generated Markdown, injects YAML frontmatter, detects sparse pages, identifies landing pages with submodule sections, and appends GitHub view links.
Python Autodoc Script
apps/playground/scripts/build-python-docs.mjs, packages/starlight-theme/scripts/build-python-docs.mjs, packages/template/scripts/build-python-docs.mjs
Node.js CLI orchestrating pydoc-markdown, performing two-pass post-processing (generation + enrichment in memory), injecting frontmatter, removing cross-ref artifacts, detecting thin pages, and writing enriched Markdown with submodule sections and GitHub links.
Playground Integration
apps/playground/astro.config.mjs, apps/playground/src/content/docs/api/auditkit.md
Updated Astro config to support BASE_URL environment variable for subpath deployments; generated API index page for auditkit module.

AI Skills: Setup and Documentation Enrichment

Layer / File(s) Summary
Skill Specifications
.claude/skills/abstract-data-docs-author/SKILL.md, .claude/skills/abstract-data-setup/SKILL.md, packages/starlight-theme/skills/claude/abstract-data-docs-author/SKILL.md, packages/starlight-theme/skills/claude/abstract-data-setup/SKILL.md, packages/template/.claude/skills/abstract-data-docs-author/SKILL.md, packages/template/.claude/skills/abstract-data-setup/SKILL.md
Markdown skill definitions specifying invocation criteria, operating principles, multi-phase workflows (12+ phases for setup, 8 phases for docs enrichment), reusable templates, and read/write file inventories.
Skill Compilation & Multi-Skill Support
scripts/compile-skill.mjs
Refactored Node.js script to read multiple SKILL.md sources, parse YAML frontmatter, generate per-skill Claude mirrors and Cursor .mdc rules, combine into unified Copilot instructions, and conditionally copy static assets.
Cursor/Claude Skill Rules & Handshake
.cursor/rules/abstract-data-docs-author.mdc, .cursor/rules/abstract-data-setup.mdc, packages/starlight-theme/skills/cursor/abstract-data-docs-author.mdc, packages/starlight-theme/skills/cursor/abstract-data-setup.mdc, packages/starlight-theme/skills/cursor/welcome.mdc, packages/starlight-theme/skills/claude/CLAUDE.md, packages/template/.cursor/rules/abstract-data-docs-author.mdc, packages/template/.cursor/rules/abstract-data-setup.mdc, packages/template/.cursor/rules/welcome.mdc, packages/template/CLAUDE.md
Compiled procedural rules for Cursor and Claude that trigger on project setup detection, offer to run automation workflows, enforce idempotent updates via HTML markers, and coordinate between setup and docs-author skills.
Copilot Instructions
.github/copilot-instructions.md, packages/starlight-theme/skills/github/copilot-instructions.md, packages/template/.github/copilot-instructions.md
GitHub Copilot reference documentation combining both skill workflows, detailing multi-stack detection, Python/TypeScript audits with thresholds, logo detection, config wiring, pre-commit hook offerings, and docs enrichment with narrative injections.

Build, Test, and Deployment Pipeline

Layer / File(s) Summary
GitHub Actions Deployment
.github/workflows/deploy-playground.yml
New workflow building and deploying playground to GitHub Pages with BASE_URL environment variable, Bun frozen lockfile installation, and actions/deploy-pages integration.
Smoke Testing
scripts/smoke-test.mjs
End-to-end validation: compiles skills, scaffolds demo project via create-docs CLI, checks required files exist, verifies theme version substitution, validates astro.config.mjs title replacement, and optionally builds the project.
Version & Package Management
scripts/sync-theme-version.mjs, packages/create-docs/package.json, packages/starlight-theme/package.json, packages/create-docs/bin/cli.js
Script reading theme version and updating create-docs CLI constant; prepack script chain ensuring version sync before template updates; package.json updated to publish scripts/ directory.
Installation & Mappings
packages/starlight-theme/bin/install-skills.js, package.json
Installer supporting per-mapping source directories (skills/ vs scripts/), enabling autodoc script distribution; added smoke-test npm script.

Template and Project Bootstrap

Layer / File(s) Summary
Create-Docs CLI Updates
packages/create-docs/bin/cli.js
Bumped theme version to ^0.3.2 and updated post-scaffold messaging to instruct users to open AI assistant and allow it to offer automated setup workflow.
Documentation & Configuration
packages/template/src/content/docs/quickstart.md, packages/template/src/content/docs/index.mdx
Expanded quickstart with installation, configuration, autodoc workflow instructions, and deployment guidance for three workflow variants; refactored splash landing with branded callouts and "Make it yours" guide.
Git & Project Config
.gitignore, packages/template/.gitignore, README.md
Enabled bun.lock tracking for reproducible installs; added live demo link to README.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Poem

🐰 Hop on, dear reader, through skills so grand,
Python and TypeScript, hand in hand!
With setup and docs on an AI quest,
This theme's docs automation is truly blessed. ✨
From thin pages to riches, submodules bright—
Let's make your docs shine, day and night!

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch update-template-docs-autodoc

@jreakin
jreakin merged commit 53f9698 into main May 8, 2026
12 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant