Skip to content

feat(docs): host searchable community preset directory - #5461

Open
mnriem wants to merge 1 commit into
github:mainfrom
mnriem:mnriem-preset-catalog-integration
Open

mnriem wants to merge 1 commit into
github:mainfrom
mnriem:mnriem-preset-catalog-integration

Conversation

@mnriem

@mnriem mnriem commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Description

Host community preset discovery within the Spec Kit documentation site instead of relying on an external browsing application.

  • Generate a searchable, tag-filterable alphabetical directory and individual DocFX detail pages directly from the community preset catalog.
  • Show catalog-listed releases, dependencies, contribution counts, source/documentation links, and repository star counts captured at build time.
  • Preserve a complete no-JavaScript listing, accessible controls, explicit unavailable-star states, and community vetting guidance.
  • Generate preset documentation during normal docs and preset-catalog deployments; no separate publishing schedule.
  • Update preset submission automation and its verifier to maintain the catalog alone rather than a duplicate Markdown table.

No CLI commands, preset contents, catalog entries, or installation trust policies change.

Testing

Set up this checkout's .venv and editable install using the local development guide. Run commands from the checkout root.

  • Tested locally with .venv/bin/specify --help (Windows PowerShell: .\.venv\Scripts\specify.exe --help)
  • Ran relevant existing tests with .venv/bin/python -m pytest tests -q (Windows PowerShell: .\.venv\Scripts\python.exe -m pytest tests -q); use affected test paths for focused checks and LC_ALL=en_US.UTF-8 on macOS
  • Tested with a sample project (if applicable)

Sample-project initialization is not applicable: this changes documentation generation and submission tooling, not installed project behavior.

  • .venv/bin/specify --help — passed.
  • .venv/bin/python -m pytest tests/test_github_workflows.py tests/test_preset_documentation.py tests/test_community_preset_validation.py tests/test_catalog_trust_docs.py tests/contract/test_catalog_schema.py -q — 348 passed.
  • node --check docs/assets/preset-catalog.js — passed.
  • GH_TOKEN="$(gh auth token)" python3 docs/generate_presets.py --fetch-stars — passed; generated all 43 current community presets. GitHub returned 403 for Spec2Cloud's stars, correctly rendered as unavailable.
  • docfx docs/docfx.json --logLevel Warning — passed with three existing documentation warnings: two parent-directory glob warnings and an unrelated broken workflow reference in docs/integrations/omp.md.
  • git diff --check — passed.

The full test suite was not run.

AI Disclosure

  • I did not use AI assistance for this contribution
  • I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored by GitHub Copilot App using GPT-6.1 Sol (model ID: gpt-6.1-sol), autonomous agent mode with default session settings, on behalf of @mnriem. AI assistance covered implementation, documentation, tests, validation, and this PR description; the contributor directed scope and publication behavior.

Generate native DocFX preset listings and detail pages from the community catalog, including build-time repository stars and trust guidance. Publish on normal documentation or catalog changes and remove duplicate table maintenance from preset submissions.

Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI adaptive review requested due to automatic review settings November 17, 2026 14:21

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Blank lines in submitter-controlled descriptions can terminate raw HTML blocks, allowing active Markdown links, including javascript: URLs, in generated documentation.

2 open issues
What changed in this PR

Moves community preset discovery into the Spec Kit documentation site, using the catalog as the single source for the directory and individual preset pages.

Changes:

  • Adds searchable, tag-filterable listings with a complete no-JavaScript fallback, release details, and build-time repository star counts.
  • Generates preset documentation during normal documentation deployments, including catalog-triggered builds.
  • Simplifies submission automation and validation to maintain only the catalog, with corresponding test updates.

AI-assisted review for the requesting contributor: GitHub Copilot (model unknown, autonomous); assistance covered investigation and review comments.

File Description
tests/​test_preset_documentation.py Adds generation, validation, star-lookup, and deployment-wiring coverage.
tests/​test_github_workflows.py Updates workflow expectations for catalog-only submissions.
tests/​test_community_preset_validation.py Replaces Markdown-table checks with catalog validation cases.
docs/​README.md Documents generation, local builds, and deployment behavior.
docs/​presets/​publishing.md Explains catalog-only submissions and generated documentation.
docs/​generate_presets.py Generates the directory and detail pages with optional star counts.
docs/​docfx.json Includes generated detail pages and directory assets.
docs/​community/​presets.md Replaces the maintained table with the generated directory include.
docs/​assets/​preset-catalog.js Adds search, tag filtering, sorting, and URL state.
docs/​assets/​preset-catalog.css Styles responsive listings, controls, and detail pages.
docs/​.gitignore Excludes generated documentation files.
.github/​workflows/​docs.yml Generates preset pages and deploys catalog changes.
.github/​workflows/​add-community-preset.md Limits submission automation to catalog updates.
.github/​workflows/​add-community-preset.lock.yml Synchronizes compiled workflow permissions and metadata.
.github/​scripts/​validate_community_preset.py Removes duplicate Markdown-table verification.

Review effort: Balanced (adaptive)

Comment thread docs/generate_presets.py
<div class="preset-detail">
<p><a href="../presets.md">Back to community presets</a></p>
<h1>{escape(entry["name"])}</h1>
<p>{escape(entry["description"])}</p>
Comment thread docs/generate_presets.py
if not isinstance(count, int) or isinstance(count, bool) or count < 0:
raise ValueError("GitHub response has no valid stargazers_count")
return count
except (OSError, ValueError) as exc:

This branch has not been deployed

No deployments
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.

2 participants