Skip to content

docs: update and expand concept documentation pages - #79

Merged
spmse merged 2 commits into
mainfrom
copilot/update-concepts-docs
Sep 14, 2026
Merged

spmse merged 2 commits into
mainfrom
copilot/update-concepts-docs

Conversation

Copilot AI commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Comprehensive overhaul of all quickli concept 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

  • Overview (quickli-concepts.md): Added framework architecture map, concept hierarchy, relationship matrix, cross-references, and admonitions.
  • Application (application.md): Documented all 4 command authoring/registration styles (@app.command, register_command, @app.entrypoint, load_plugin), execution models (run() vs main()), global option streams, shell completion generation, and custom error handlers.
  • Command (command.md): Detailed decorator, imperative (Command), and docstring authoring styles, name normalization rules, signature binding, and Subcommand nesting hierarchies.
  • Argument (argument.md): Outlined positional ordering rules, optional/default mechanics, built-in/custom validators (file_path, number_range), metavar formatting, and argument vs option decision guides.
  • Option (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 (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 (parsers.md): Detailed JSON/YAML/TOML serialization/deserialization helpers, argument converter integration, CLI format selection flags, and parser vs config comparison.
  • Plugin (plugin.md): Documented Plugin contract (name, description, register()), load_plugin lifecycle, inspection via app.plugins, duplicate protection (PluginLoadError), and roadmap.

Code Snippet

from quickli import Application, Subcommand, positive_number

app = Application(name="demo", version="1.0.0")

# Decorator command authoring with typed arguments, options, and validators
@app.command(name="serve", description="Start service node")
def serve(
    host: str = app.argument(default="127.0.0.1", help="Bind address"),
    port: int = app.option("-p", "--port", default=8080, validator=positive_number(), help="Listen port"),
    verbose: bool = app.option("-v", "--verbose", is_flag=True, help="Verbose log output"),
):
    ...

# Imperative subcommand group registration
db_group = Subcommand(name="db", description="Database administration")
app.register_command(db_group)

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 pytest
  • python -m build --sdist --wheel
  • Not applicable

Docusaurus production build verified cleanly via corepack pnpm --filter quickli-docs build across both en and de locales with zero broken anchor links or build warnings.

Documentation

  • Documentation was updated where needed.
  • No documentation update was needed.

Scope

  • This pull request is focused on one feature or fix.
  • Tests were added or updated for functional changes.
  • Assumptions, risks, or follow-up work are described below.

Risks or follow-up

  • German localized documentation (i18n/de) was synchronized concurrently; future modifications to English concept docs must maintain parity with the German localization files.

Copilot AI linked an issue Sep 6, 2026 that may be closed by this pull request
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
Copilot AI requested a review from spmse September 6, 2026 08:04
@spmse
spmse marked this pull request as ready for review September 14, 2026 06:17
@spmse
spmse merged commit a71bda2 into main Sep 14, 2026
5 checks passed
@spmse
spmse deleted the copilot/update-concepts-docs branch September 14, 2026 06:19
@github-actions github-actions Bot mentioned this pull request Sep 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update concepts docs

2 participants