docs: comprehensive narrative documentation#7
Merged
Conversation
Add narrative guides for the previously-undocumented subsystems: services (dependency injection), request/response, views & controllers, viewlets, Tonnikala templating, i18n, static assets, and decorators. Each page is grounded in the actual source APIs. Audit and correct the existing narrative pages (configuration, json, sqlalchemy, security, utilities, testing) against the real code -- utilities and testing were largely rewritten as the originals documented many nonexistent APIs. Refresh the introduction (0.5.0 / Python 3.8+) and reorganize the narrative index into logical sections. Normalize RST heading underlines and fix an i18n table / XSS-demo code-block so the Sphinx build is warning-free for the narrative and tutorial docs.
Add the rstcheck hook (pinned v6.2.5, rstcheck[sphinx,toml]) to validate RST. Configure [tool.rstcheck] to ignore Sphinx autodoc directives (used in the auto-generated docs/api stubs) and report at WARNING level. Fix a genuine error it caught: a 'def __getitem__' example in views.rst was written as 'class __getitem__'.
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
Comprehensive narrative documentation for the Tet framework, grounded in the actual source APIs.
New guides (previously undocumented subsystems)
tet.services, request-scoped services,autowired,ServiceViews.view_config, class-based controllers, theexposedecorator.$/${...}/$literalsyntax.configure_i18n,request.translate/pluralize, template globals.deprecatedandreify_attr.Audited & corrected existing pages
Verified
configuration,json,sqlalchemy,security,utilities, andtestingagainst the real code.utilitiesandtestingwere largely rewritten — the originals documented many APIs that don't exist. Refreshed the introduction (0.5.0 / Python 3.8+) and reorganized the narrative index into logical sections.Housekeeping
sphinx-buildcompletes with no warnings/errors for the narrative and tutorial docs.Scope
Documents the framework as it exists on
master. The auth/MFA security subsystem (PR #6) will be documented once it merges.