diff --git a/packages/quickli-docs/docs/concepts/application.md b/packages/quickli-docs/docs/concepts/application.md index a2efb58..dc5480d 100644 --- a/packages/quickli-docs/docs/concepts/application.md +++ b/packages/quickli-docs/docs/concepts/application.md @@ -100,13 +100,16 @@ print(app.run(["build"])) # building… ## Tips -:::tip Single action vs. multiple commands +:::note[Single action vs. multiple commands] + Use `@app.entrypoint` for a single-action tool (like `cat` or `head`) and `@app.command` for a multi-action tool (like `git` or `kubectl`). You can always add commands later — the entrypoint acts as a fallback when no command name matches. + ::: -:::tip Wrapping `run()` in an executable +:::tip[Wrapping `run()` in an executable] + `Application.run()` reads `sys.argv[1:]` by default and returns a string result. Printing and exit-code handling belong to your `main()` wrapper so that the application stays independently testable. @@ -118,6 +121,7 @@ if __name__ == "__main__": Pass an explicit list to override the default: `app.run(["greet", "Ada"])`. Set `auto_sys_argv=False` at construction to disable automatic reading entirely. + ::: ## Where to go next diff --git a/packages/quickli-docs/docs/concepts/argument.md b/packages/quickli-docs/docs/concepts/argument.md index f11caf9..d42864a 100644 --- a/packages/quickli-docs/docs/concepts/argument.md +++ b/packages/quickli-docs/docs/concepts/argument.md @@ -95,7 +95,7 @@ If required arguments are missing, command execution fails with a deterministic ## Tips -:::tip Argument vs. Option +:::tip[Argument vs. Option] Use an `Argument` when the value is the *subject* of the command — the thing the command acts on (a file path, a name, an ID). Use an `Option` when the value *modifies how* the command behaves (a format, a verbosity level, a boolean flag). @@ -109,7 +109,7 @@ cat --format json myfile.txt ``` ::: -:::tip Order matters +:::tip[Order matters] Arguments are matched positionally in the order they are declared. Place required arguments before optional ones to keep the command signature predictable. ::: diff --git a/packages/quickli-docs/docs/concepts/command.md b/packages/quickli-docs/docs/concepts/command.md index c22c8ff..fd27e86 100644 --- a/packages/quickli-docs/docs/concepts/command.md +++ b/packages/quickli-docs/docs/concepts/command.md @@ -94,13 +94,13 @@ print(app.run(["env", "create", "dev"])) ## Tips -:::tip Command vs. Subcommand +:::tip[Command vs. Subcommand] Use a top-level `@app.command` for actions that are independent of each other, such as `build` and `clean`. Use a `Subcommand` when actions logically share a namespace, such as `env create`, `env list`, and `env delete`. ::: -:::tip Help text from docstrings +:::tip[Help text from docstrings] If you do not pass `help_text`, `quickli` automatically uses the function's docstring. This keeps your handler code self-documenting. diff --git a/packages/quickli-docs/docs/concepts/config.md b/packages/quickli-docs/docs/concepts/config.md index 36faa55..67e9f70 100644 --- a/packages/quickli-docs/docs/concepts/config.md +++ b/packages/quickli-docs/docs/concepts/config.md @@ -84,14 +84,14 @@ Both are subclasses of `CLIError`. ## Tips -:::tip Config vs. Option for persistent settings +:::tip[Config vs. Option for persistent settings] Use a **config file** for settings that users set once and expect to persist between runs — for example, a default server host or an API base URL. Use a **command option** for settings that change on a per-invocation basis, such as the output format or a one-off target path. ::: -:::tip Auto-init on first run +:::tip[Auto-init on first run] `add_auto_init_config` is the recommended way to initialise a config file. It writes a file with all default values on the first run so the user has a concrete starting point to edit. On every subsequent run it loads and validates the existing file. diff --git a/packages/quickli-docs/docs/concepts/option.md b/packages/quickli-docs/docs/concepts/option.md index 41a169b..325aff9 100644 --- a/packages/quickli-docs/docs/concepts/option.md +++ b/packages/quickli-docs/docs/concepts/option.md @@ -60,6 +60,7 @@ print(app.run(["write", "hello"])) # writing 'hello' to out. print(app.run(["write", "hello", "--output", "a.txt"])) # writing 'hello' to a.txt ``` + ## Boolean flag example ```python @@ -83,6 +84,11 @@ print(app.run(["version", "--verbose"])) # demo version 1.0.0 (debug build) print(app.run(["version", "-v"])) # demo version 1.0.0 (debug build) ``` +:::tip[Flags for on/off switches] +Use `is_flag=True` when the option represents a boolean toggle that does not take a +value. The presence of the flag sets it to `True`; its absence leaves it as `False`. +::: + ## Repeatable option example ```python @@ -125,23 +131,18 @@ print(app.run(["build", "--verbose"])) # building… (verbose=True) ## Tips -:::tip Argument vs. Option +:::note[Argument vs. Option] Use an `Argument` for the primary subject of the command (what it acts on). Use an `Option` for anything that *changes how* the command behaves — output format, verbosity, a toggle, or a secondary target. ::: -:::tip Local vs. global options +:::tip[Local vs. global options] Define an option as **local** when it only makes sense for one command (like `--output` for a write command). Define it as **global** when it should apply to every command in the application (like `--verbose` or `--config`). ::: -:::tip Flags for on/off switches -Use `is_flag=True` when the option represents a boolean toggle that does not take a -value. The presence of the flag sets it to `True`; its absence leaves it as `False`. -::: - ## Where to go next - Use **[Arguments](./argument.md)** for positional, ordered input. diff --git a/packages/quickli-docs/docs/concepts/parsers.md b/packages/quickli-docs/docs/concepts/parsers.md index 9a780aa..a42f2a1 100644 --- a/packages/quickli-docs/docs/concepts/parsers.md +++ b/packages/quickli-docs/docs/concepts/parsers.md @@ -60,7 +60,7 @@ print(app.run(["summarise", "data.json"])) ## Tips -:::tip Which format to choose +:::tip[Which format to choose] - Use **JSON** for machine-to-machine data and API responses. - Use **YAML** for human-edited configuration and Kubernetes-style manifests. - Use **TOML** for end-user configuration files (see [Configuration Files](./config.md)). @@ -69,7 +69,7 @@ All three helpers are available from the top-level `quickli` import, so you do n to import `quickli.parsers` directly. ::: -:::tip Parsers vs. Config +:::tip[Parsers vs. Config] `load_toml` / `render_toml` are useful for one-off parsing of TOML strings or files that you manage yourself. For persistent application configuration with schema validation and auto-initialisation, use the dedicated [Config](./config.md) resources instead. diff --git a/packages/quickli-docs/docs/concepts/plugin.md b/packages/quickli-docs/docs/concepts/plugin.md index 5c64e31..a7c3c5d 100644 --- a/packages/quickli-docs/docs/concepts/plugin.md +++ b/packages/quickli-docs/docs/concepts/plugin.md @@ -88,14 +88,14 @@ except quickli.PluginLoadError as error: ## Tips -:::tip When to use a plugin +:::tip[When to use a plugin] Use a plugin when you want to package a reusable set of commands as a separate Python module or package. For example, a shared `audit` plugin can be loaded into any team's CLI without copying code. For small, app-specific commands, just use `@app.command` directly. ::: -:::tip Plugins cannot override existing commands +:::warning[Plugins cannot override existing commands] A plugin cannot replace a command that has already been registered — either by the application itself or by an earlier plugin. Design your plugins to add new commands rather than replace existing ones. diff --git a/packages/quickli-docs/docs/concepts/quickli-concepts.md b/packages/quickli-docs/docs/concepts/quickli-concepts.md index ce248ae..1cf918d 100644 --- a/packages/quickli-docs/docs/concepts/quickli-concepts.md +++ b/packages/quickli-docs/docs/concepts/quickli-concepts.md @@ -57,7 +57,7 @@ In a typical flow: | Persist user settings between runs | `Config` | | Parse or produce JSON, YAML, or TOML | `parsers` helpers | -:::tip Not sure where to start? +:::note[Not sure where to start?] Read [Getting Started](../getting-started.md) first, then come back here to explore the individual concepts in detail. ::: diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/application.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/application.md index 874310b..afa0f8b 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/application.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/application.md @@ -101,13 +101,13 @@ print(app.run(["build"])) # building… ## Tipps -:::tip Einzelaktion vs. mehrere Befehle +:::note[Einzelaktion vs. mehrere Befehle] Verwende `@app.entrypoint` für ein Einzelaktions-Tool (wie `cat` oder `head`) und `@app.command` für ein Multi-Aktions-Tool (wie `git` oder `kubectl`). Du kannst jederzeit Befehle hinzufügen — der Einstiegspunkt wirkt als Fallback, wenn kein Befehlsname passt. ::: -:::tip `run()` in einem Wrapper aufrufen +:::tip[`run()` in einem Wrapper aufrufen] `Application.run()` liest `sys.argv[1:]` standardmäßig und gibt einen String zurück. Ausgabe und Exit-Code-Behandlung gehören in deinen `main()`-Wrapper, damit die Anwendung unabhängig testbar bleibt. diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/argument.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/argument.md index 71b2277..c9d401a 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/argument.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/argument.md @@ -99,7 +99,7 @@ Fehler fehl. ## Tipps -:::tip Argument vs. Option +:::tip[Argument vs. Option] Verwende ein `Argument`, wenn der Wert das *Subjekt* des Befehls ist — das, worauf der Befehl wirkt (ein Dateipfad, ein Name, eine ID). Verwende eine `Option`, wenn der Wert *verändert, wie* der Befehl sich verhält (ein Format, ein Ausführlichkeitsgrad, ein @@ -114,7 +114,7 @@ cat --format json myfile.txt ``` ::: -:::tip Reihenfolge ist wichtig +:::tip[Reihenfolge ist wichtig] Argumente werden positional in der Reihenfolge abgeglichen, in der sie deklariert wurden. Platziere erforderliche Argumente vor optionalen, um die Befehlssignatur vorhersehbar zu halten. diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/command.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/command.md index d85dccb..0cbbad5 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/command.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/command.md @@ -96,13 +96,13 @@ print(app.run(["env", "create", "dev"])) ## Tipps -:::tip Command vs. Subcommand +:::tip[Command vs. Subcommand] Verwende einen Top-Level-`@app.command` für voneinander unabhängige Aktionen wie `build` und `clean`. Verwende einen `Subcommand`, wenn Aktionen logisch einen gemeinsamen Namensraum teilen, z. B. `env create`, `env list` und `env delete`. ::: -:::tip Hilfetext aus Docstrings +:::tip[Hilfetext aus Docstrings] Wenn du kein `help_text` übergibst, verwendet `quickli` automatisch den Docstring der Funktion. Dadurch bleibt der Handler-Code selbst dokumentierend. diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/config.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/config.md index 784e320..69714eb 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/config.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/config.md @@ -84,14 +84,14 @@ Beide sind Unterklassen von `CLIError`. ## Tipps -:::tip Config vs. Option für persistente Einstellungen +:::tip[Config vs. Option für persistente Einstellungen] Verwende eine **Konfigurationsdatei** für Einstellungen, die Nutzer einmal setzen und zwischen Ausführungen beibehalten möchten — zum Beispiel einen Standard-Serverhost oder eine API-Basis-URL. Verwende eine **Befehlsoption** für Einstellungen, die sich pro Ausführung ändern, etwa das Ausgabeformat oder einen einmaligen Zielpfad. ::: -:::tip Auto-Init beim ersten Start +:::tip[Auto-Init beim ersten Start] `add_auto_init_config` ist der empfohlene Weg, eine Konfigurationsdatei zu initialisieren. Beim ersten Start schreibt es eine Datei mit allen Standardwerten, damit der Nutzer einen konkreten Ausgangspunkt zum Bearbeiten hat. Bei jedem weiteren Start lädt und validiert es diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/option.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/option.md index e343484..e912e5c 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/option.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/option.md @@ -126,19 +126,19 @@ print(app.run(["build", "--verbose"])) # building… (verbose=True) ## Tipps -:::tip Argument vs. Option +:::note[Argument vs. Option] Verwende ein `Argument` für das primäre Subjekt des Befehls (worauf er wirkt). Verwende eine `Option` für alles, was *verändert, wie* der Befehl sich verhält — Ausgabeformat, Ausführlichkeitsgrad, ein Schalter oder ein sekundäres Ziel. ::: -:::tip Lokale vs. globale Optionen +:::tip[Lokale vs. globale Optionen] Definiere eine Option als **lokal**, wenn sie nur für einen Befehl sinnvoll ist (wie `--output` für einen Schreibbefehl). Definiere sie als **global**, wenn sie für jeden Befehl in der Anwendung gelten soll (wie `--verbose` oder `--config`). ::: -:::tip Schalter für An/Aus-Umschalter +:::tip[Schalter für An/Aus-Umschalter] Verwende `is_flag=True`, wenn die Option einen booleschen Schalter darstellt, der keinen Wert annimmt. Das Vorhandensein des Flags setzt es auf `True`; sein Fehlen lässt es auf `False`. diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/parsers.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/parsers.md index 4c7b4dc..1fa4883 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/parsers.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/parsers.md @@ -61,7 +61,7 @@ print(app.run(["summarise", "data.json"])) ## Tipps -:::tip Welches Format wählen +:::tip[Welches Format wählen] - Verwende **JSON** für maschinelle Kommunikation und API-Antworten. - Verwende **YAML** für manuell bearbeitete Konfigurationen und Kubernetes-ähnliche Manifeste. - Verwende **TOML** für endnutzerorientierte Konfigurationsdateien (siehe [Konfigurationsdateien](./config.md)). @@ -70,7 +70,7 @@ Alle drei Helfer sind über den Top-Level-Import `quickli` verfügbar, du musst `quickli.parsers` nicht direkt importieren. ::: -:::tip Parser vs. Config +:::tip[Parser vs. Config] `load_toml` / `render_toml` sind nützlich für einmaliges Parsen von TOML-Strings oder Dateien, die du selbst verwaltest. Für persistente Anwendungskonfiguration mit Schema-Validierung und Auto-Initialisierung verwende stattdessen die dedizierten diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/plugin.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/plugin.md index 84fcbe8..2d3e96e 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/plugin.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/plugin.md @@ -88,14 +88,14 @@ except quickli.PluginLoadError as error: ## Tipps -:::tip Wann ein Plugin verwenden +:::tip[Wann ein Plugin verwenden] Verwende ein Plugin, wenn du einen wiederverwendbaren Befehlssatz als separates Python-Modul oder -Paket verpacken möchtest. Ein gemeinsames `audit`-Plugin kann z. B. in jede Team-CLI geladen werden, ohne Code zu kopieren. Für kleine, anwendungsspezifische Befehle verwende einfach direkt `@app.command`. ::: -:::tip Plugins können keine bestehenden Befehle überschreiben +:::warning[Plugins können keine bestehenden Befehle überschreiben] Ein Plugin kann keinen Befehl ersetzen, der bereits registriert wurde — weder von der Anwendung selbst noch von einem früheren Plugin. Entwirf deine Plugins so, dass sie neue Befehle hinzufügen und keine bestehenden ersetzen. diff --git a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/quickli-concepts.md b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/quickli-concepts.md index f41acea..38fde6e 100644 --- a/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/quickli-concepts.md +++ b/packages/quickli-docs/i18n/de/docusaurus-plugin-content-docs/current/concepts/quickli-concepts.md @@ -58,7 +58,7 @@ In einem typischen Ablauf: | Benutzereinstellungen zwischen Ausführungen speichern | `Config` | | Strukturierte Daten als JSON, YAML oder TOML lesen/schreiben | `parsers`-Helfer | -:::tip Nicht sicher, wo du anfangen sollst? +:::note[Nicht sicher, wo du anfangen sollst?] Lies zuerst [Erste Schritte](../getting-started.md) und schau dann hier nach, um die einzelnen Konzepte im Detail zu erkunden. :::