docs: sync guides + reference + release with current code - #122
Merged
Conversation
- Fix Vite dev port (5050, not 5173) in installation, e2e-testing, make-commands. - Update scaffold output description to match `scripts/new_module.py`: drop the non-existent `test_service.py` / `test_api.py`, mention the `services.py` state container, the per-module `package.json` / `tsconfig.json`, and `test_<name>.py` as the generated test path. - Rewrite the `MenuItem` example in first-module.md to use the actual fields (`label`, `url`, `group`) rather than the imagined `label_key`, `href`, `required_permission`. Drop the `prefix=` arg from `register_routes`, since `route_prefix` / `view_prefix` from `ModuleMeta` already prefix the routers. - Modernize the per-module settings example in configuration.md to use `pydantic_settings.BaseSettings` + `SettingsConfigDict` instead of the v1-era `class Config:` style. - Add `worker` / `beat` / `worker-docker` and the bench / memray / loadtest targets to make-commands.md. - Document `SM019` in diagnostic-codes.md. - Fix release.md package counts (13 PyPI / 16 total, not 14 / 17) and note that the workflow now creates the GitHub Release automatically. - Drop the stale `simple_module_products` and rename `simple_module_testing` to `simple_module_test` in CHANGELOG.md. https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
Deploying simple-module-python with
|
| Latest commit: |
b298ec2
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://ed61b23f.simple-module-python.pages.dev |
| Branch Preview URL: | https://claude-update-docs-xkyrt.simple-module-python.pages.dev |
Adds docs/modules/<name>.md for auth, users, permissions, settings, feature_flags, file_storage, background_tasks, and dashboard, plus a catalog index at docs/modules/index.md. Each page covers the module's ModuleMeta, routes (API + view) with permissions, public contracts, DB models, settings (DB-backed + bootstrap env vars), permissions, menu entries, events, tasks, CLI, and Inertia pages. Wires the new section into the top nav and sidebar, and links it from the home page section list. Grounded in the current code: every route path, DTO name, model column, setting field, permission key, and menu order quoted is verified against the source under modules/<name>/. https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
- auth.md: drop the negative-space "what this module does not do" list; keep the cross-link to permissions.md for direct-grant checks. - file_storage.md: remove the placeholder feature-flag section (file_storage.public_uploads is reserved for future use, not live). - settings.md: replace the duplicated register_module_settings walkthrough with a link to /guide/configuration; keep only the module-specific value-add (DB hydration, env-var migration, hot reload). https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
Landing page (docs/index.md): - Reframe the hero CTAs around real journeys (Quickstart vs Why) so visitors land in the right place on the first click. - Replace the 6-feature grid with 4 task-oriented feature cards (Build with it / Author a module / Use a bundled module / Operate in production), each with a primary action link. - Replace the "What you'll find here" bullet list with a 7-card grid rendered via a small <style> block scoped to the home page — keeps every section discoverable without burying it in prose. - Add a "Try it in 60 seconds" snippet so readers see the value loop without leaving the page. - Add a "Where to start" section with explicit on-ramps for new users, returning users, module shoppers, and operators. Cross-link coherence: - Standardize the next-steps section heading to "## Next steps" across framework/overview, database/models, testing/overview, and guide/quickstart (was a mix of "What's next", "Where to go from here", "Next", "Where to go next"). - Add a Next steps footer to docs/modules/index.md and docs/reference/make-commands.md (didn't have one). - Expand framework/overview Next steps to include the bundled modules. - Expand guide/first-module Next steps to point at modules/settings, database/mixins, and module-authoring as the natural follow-on reads after shipping a first module. https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
- Drop manual "→" suffix from feature card linkText: VitePress's VPFeature component already appends a VPIconArrowRight when a link/linkText pair is set, so the manual arrow renders twice. - Wrap the home-card hover transform in a @media (prefers-reduced-motion: no-preference) block so users with reduced motion enabled don't get the lift animation. - Soften "wired into the running app on the next reload" to "wired in once the dev server reloads" — clearer that a uvicorn restart is the trigger. - first-module Next steps: drop the standalone "Database / Mixins" bullet (already linked from the Database / Models page next-steps). https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
antosubash
marked this pull request as ready for review
May 3, 2026 17:39
Until now the docs assumed users would clone the simple_module_python repo and run framework-internal make targets (make new-module, make doctor, make migration, make lint, make test). That conflates the framework's contributor flow with what end users do. End users install simple_module_cli, run sm new myapp, and work inside the resulting project. This rewires the user-facing pages around that reality: Bootstrap (the entry path): - index.md "Try it in 60 seconds" snippet: uv tool install simple_module_cli + sm new myapp, no git clone. - guide/installation.md: full rewrite around uv tool install simple_module_cli, sm new <preset> + --with, sm package-update. - guide/quickstart.md: starts from sm new myapp --yes; step 5 now uses sm create-module orders --dest modules/orders + uv add ./modules/orders. - guide/first-module.md: same scaffold path; alembic invocations are uv run alembic ... directly; "Verify end-to-end" no longer leans on make doctor / make lint (boot diagnostics cover it). Project shape: - guide/project-structure.md: rewritten to describe the tree sm new produces (main.py, migrations/, client_app/, modules/), not the framework repo's host/+framework/+modules/+packages/ layout. Reference: - reference/make-commands.md: restructured into "sm CLI" + "scaffolded app's Makefile" + "routine ops without a target" + a final note that the framework repo's bigger Makefile is a contributor convenience. Sidebar label renamed to "Commands". - reference/diagnostic-codes.md: rewritten so the trigger is "app boot" rather than "make doctor"; SM011/SM017 fixes use uv run alembic and sm create-module. - reference/deployment.md: Dockerfile uses main:app and client_app/ paths from the scaffold; production-readiness check is "boot in SM_ENVIRONMENT=production produces no errors", not make doctor. Internal pages swept: - database/migrations.md, database/per-module-base.md: paths point at migrations/env.py + alembic.ini (no host/ prefix); make migration msg=... replaced with uv run alembic revision --autogenerate -m ... - testing/overview.md, e2e-testing.md: make test* swapped for uv run pytest / cd client_app && npx vitest run. - framework-conventions.md, framework/i18n.md, framework/discovery.md, framework/overview.md, frontend/pages.md, frontend/inertia.md, guide/introduction.md: replaced make new-module → sm create-module, make doctor → "boot diagnostics", host/client_app → client_app, uvicorn host.main:app → uvicorn main:app. - module-authoring.md: migration path host/migrations/... → migrations/... The only remaining make-target references in user-facing docs are for targets that the scaffolded app's Makefile actually ships (dev, install, migrate, build, gen-pages, sync-js-deps) — no framework-only ones. https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
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
2 participants
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
Full audit pass over
docs/to fix drift accumulated since the v0.0.5–v0.0.8 releases (datasets/products module removal,simple_module_testrename, sidebar reorg,sm package-updateCLI, worker status admin page, GitHub Release auto-creation, scaffold rework).Guide
installation.md,e2e-testing.md,make-commands.md— Vite dev port is5050, not5173(host/client_app/vite.config.ts:76).make killfrees8000, 5050, 5173.quickstart.md,project-structure.md— match whatscripts/new_module.pyactually scaffolds: includeservices.py(module-scoped state container),package.json+tsconfig.json(so SM017 doesn't fire), andtests/test_<name>.py. Drop the imaginedtest_service.py/test_api.py.first-module.md—MenuItemuseslabel/url/group, notlabel_key/href/required_permission(the latter doesn't exist onMenuItem; menu filtering is viaroles=[...]).register_routesshouldn't re-addprefix=—ModuleMeta.route_prefix/view_prefixalready prefixes the routers.configuration.md— modernize the per-module settings example topydantic_settings.BaseSettings+SettingsConfigDict(env_prefix=...), matching what e.g.modules/users/users/settings.pyactually does.Reference
make-commands.md— add the previously undocumentedworker/beat/worker-dockertargets and thebench/memray-run/memray-flamegraph/loadtest/loadtest-memrayperf targets, plussync-module-deps.diagnostic-codes.md— add theSM019row (view routes registered without a sidebar entry or permissions).Release
release.md— Counts updated: 13 Python packages publish to PyPI (was 14) and 16 total (was 17). The current matrix in.github/workflows/release.ymlis: cli, core, db, hosting, test, auth, background_tasks, dashboard, feature_flags, file_storage, permissions, settings, users.release.md— Step 4 no longer says "create the GitHub Release manually": thefinalizejob now does it automatically (gh release create … --generate-notes, added in ci: bump deprecated Node 20 actions + auto-create GitHub Release #104).CHANGELOG.md— drop the removedsimple_module_productsand renamesimple_module_testing→simple_module_test(matchingframework/testing/pyproject.toml:2).Test plan
cd docs && npm install && npm run devrenders the changed pages without VitePress errors.make doctorstill reportsSM019exactly as the new docs row describes.git grep -n 5173 docs/returns onlydocs/README.md(VitePress dev server) and historicaldocs/superpowers/plans.make new-module name=demoproduces the file list now described inquickstart.md.https://claude.ai/code/session_01RGZVZ9HaaF3DeAR66CqUgi
Generated by Claude Code