Repository navigation
docs: update and expand concept documentation pages - #79
Merged
Merged
Conversation
Closed
Co-authored-by: spmse <24510156+spmse@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Update concepts documentation to enhance clarity and examples
docs: update and expand concept documentation pages
Sep 6, 2026
spmse
approved these changes
Sep 14, 2026
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
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 overhaul of all
quickliconcept documentation pages across English (docs/concepts/) and German (i18n/de/.../concepts/) locales to ensure explicit behavioral specs, exhaustive capability coverage, code examples for all authoring patterns, cross-references, and Docusaurus admonitions.Key Changes by Concept
quickli-concepts.md): Added framework architecture map, concept hierarchy, relationship matrix, cross-references, and admonitions.application.md): Documented all 4 command authoring/registration styles (@app.command,register_command,@app.entrypoint,load_plugin), execution models (run()vsmain()), global option streams, shell completion generation, and custom error handlers.command.md): Detailed decorator, imperative (Command), and docstring authoring styles, name normalization rules, signature binding, andSubcommandnesting hierarchies.argument.md): Outlined positional ordering rules, optional/default mechanics, built-in/custom validators (file_path,number_range),metavarformatting, and argument vs option decision guides.option.md): Detailed POSIX/GNU flag forms (-vxf,--opt=val), boolean flags vs value options, repeatable list/count options (multiple=True), and global vs local scoping.config.md): Documented TOML schema declarations (ConfigSchema,ConfigField), auto-init bootstrapping (add_auto_init_config), validation findings (error/warning), schema generation, and exception handling.parsers.md): Detailed JSON/YAML/TOML serialization/deserialization helpers, argument converter integration, CLI format selection flags, and parser vs config comparison.plugin.md): DocumentedPlugincontract (name,description,register()),load_pluginlifecycle, inspection viaapp.plugins, duplicate protection (PluginLoadError), and roadmap.Code Snippet
Why
The existing concept documentation contained implicit assumptions, lacked coverage for alternative registration patterns and execution models, omitted cross-references between quickli building blocks, and lacked structured admonitions for key gotchas and best practices.
Validation
python -m ruff check .python -m ruff format --check .python -m pytestpython -m build --sdist --wheelDocusaurus production build verified cleanly via
corepack pnpm --filter quickli-docs buildacross bothenanddelocales with zero broken anchor links or build warnings.Documentation
Scope
Risks or follow-up
i18n/de) was synchronized concurrently; future modifications to English concept docs must maintain parity with the German localization files.