Astro docs monorepo + API autodoc pipeline#622
Open
tony wants to merge 24 commits into
Open
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #622 +/- ##
=======================================
Coverage 45.39% 45.39%
=======================================
Files 22 22
Lines 2249 2249
Branches 360 360
=======================================
Hits 1021 1021
Misses 1082 1082
Partials 146 146 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
why: Establish the Astro-based docs pipeline and site structure alongside the existing Sphinx docs. what: - Add pnpm workspace with Biome/TS configs and AGENTS guidance - Introduce core API scan/model/intersphinx packages with tests - Add Astro autodoc/intersphinx packages and a starter docs site
why: Biome 2.x rejects the legacy --apply flag used by workspace scripts. what: - Update biome scripts to use --write for check and lint steps - Keep formatting commands consistent across all packages
why: Plain `import x` nodes were losing module names, breaking scans and snapshots. what: - Normalize module resolution for ast.Import nodes - Narrow walkPyNodes to qualname-bearing nodes - Refresh py-ast and api-model snapshots
why: Snapshot tests need committed baselines to stay deterministic. what: - Add vitest snapshot for core intersphinx parser
why: Ensure the site test target has at least one passing test. what: - Add a minimal vitest smoke test for the docs workspace
why: Workspace type-checks should succeed without pulling in unrelated sources. what: - Widen rootDir and clear paths in package tsconfig files - Add local *.astro module declarations for Astro packages and site
why: Keep Astro and core packages consistent with Biome formatting rules. what: - Normalize import ordering and line wrapping across packages - Update CSS and test file formatting for consistency
why: Node ESM resolution fails on extensionless TS imports during Astro dev. what: - Add .ts extensions for local exports/imports in core and Astro packages - Enable allowImportingTsExtensions in the workspace tsconfig
why: Avoid clashing with the default Astro dev port. what: - Configure the docs site server port in astro.config.ts
why: Capture the agreed tiered design and build plan for the Astro autodoc stack. what: - add notes/plan.md with phased build plan and testing scope - add notes/architecture.md with tiers, data flow, and schema firewall
why: Align the docs tooling with the tiered autodoc architecture and enable Python-backed API extraction. what: - move the Astro workspace into tiered packages/apps with updated configs - add schema, bridge, introspect, and core packages with tests and snapshots - add the pyautodoc sidecar CLI and wire py-parse + astro-autodoc
why: Reflect the current repo structure and sidecar status. what: - record tiered workspace layout and config filenames - note current implementation state for parse vs introspect
why: Keep the new autodoc packages aligned with Biome formatting rules. what: - apply Biome formatting to schema and Python bridge/introspection modules
why: Provide real runtime introspection data for API docs and docstring rendering. what: - add sidecar introspection helpers with signatures, members, and docstring HTML - expand introspection schema and wire annotation format options - update sidecar CLI and schema tests; add docutils dependency
why: API pages need signatures, annotations, and rendered docstrings from Python. what: - extend api-model schema/output to include docstring HTML and annotation values - merge py-introspect payloads into build output with updated snapshots - render introspected docstrings in astro-autodoc components and load hook
why: Introspection failed because the docs app resolved the wrong repo root. what: - correct the repo root path used by the Astro docs app - unignore astro apps src/lib so api helpers are tracked
why: Introspection fails when optional dependencies like pytest are missing. what: - add mock-import/autodoc-mock support in the sidecar CLI - wire mock options through py-introspect and astro-autodoc - default libtmux docs to mock pytest during introspection
why: We need a lightweight docstring renderer without Sphinx/docutils warnings. what: - add @libtmux/rst-lite package with parser/renderer and extensible AST - snapshot-driven tests covering headings, lists, directives, and inline roles - wire workspace tsconfig and lockfile updates
why: Replace docutils HTML with deterministic RST-lite rendering for docstrings. what: - add rst-lite docstring rendering helper and tests - wire render mode into loadApiPackage options and docs app - add rst-lite dependency for astro-autodoc
why: astro/python/pyautodoc_sidecar is a separate Python package shipped alongside the docs build pipeline. Master's stricter ruff rules (TRY003, EM102, PERF203, PERF401, SIM102, plus E501 line-length cap) flag 17 violations in the sidecar's existing code. The sidecar should be free to follow its own style budget without churning the main library config. what: - add per-file-ignores entry for astro/python/** that disables E501, EM102, PERF203, PERF401, SIM102, and TRY003 in the sidecar tree - apply ruff --fix and ruff format auto-fixes (I001 import sort, whitespace normalization in 3 files) - core libtmux source remains under the strict ruleset
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Testing