docs, cli: enforce package-bound docs, add template scaffolding, and document CLI usage

- Restrict mkdocstrings generation to real Python packages (require __init__.py)
- Add explicit documentation section for CLI scaffolding and templates
- Generalize CLI to support multiple templates with dynamic discovery
- Package templates correctly for importlib.resources access
- Add fully documented health_app template (app entry point and handlers)
- Fix setuptools package-data configuration for bundled templates

These changes make documentation import-safe, clarify package boundaries,
and provide a deterministic, OpenAPI-first scaffolding workflow via CLI.
This commit is contained in:
2026-01-11 19:26:21 +05:30
parent 6180443327
commit 72b5be6976
13 changed files with 273 additions and 74 deletions

View File

@@ -1,3 +1,31 @@
"""
Application entry point for an OpenAPI-first FastAPI service.
This module constructs a FastAPI application exclusively from an
OpenAPI specification and a handler namespace, without using
decorator-driven routing.
All HTTP routes, methods, and operation bindings are defined in the
OpenAPI document referenced by ``openapi_path``. Python callables
defined in the ``routes`` module are bound to OpenAPI operations
strictly via ``operationId``.
This module contains no routing logic, request handling, or framework
configuration beyond application assembly.
Design guarantees:
- OpenAPI is the single source of truth
- No undocumented routes can exist
- Every OpenAPI operationId must resolve to exactly one handler
- All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example:
uvicorn main:app
"""
from openapi_first.app import OpenAPIFirstApp
import routes