From fe2cf9da9d9688627a5c873b9a00e80e657eaba6 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 14 Mar 2026 18:58:10 -0500 Subject: [PATCH 1/3] ai(rules[AGENTS]): Add shell command formatting rules for docs why: Standardize shell code blocks for copy-pastability and readability what: - Add console language tag + $ prefix rule - Add line continuation rule for wide multi-flag commands - Scope to documentation shell examples, not doctests --- AGENTS.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 8cd72efc9..2fee1b306 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -436,7 +436,7 @@ EOF When writing documentation (README, CHANGES, docs/), follow these rules for code blocks: -**One command per code block.** This makes commands individually copyable. +**One command per code block.** This makes commands individually copyable. For sequential commands, either use separate code blocks or chain them with `&&` or `;` and `\` continuations (keeping it one logical command). **Put explanations outside the code block**, not as comments inside. @@ -464,6 +464,42 @@ $ uv run pytest $ uv run pytest --cov ``` +### Shell Command Formatting + +These rules apply to shell commands in documentation (README, CHANGES, docs/), **not** to Python doctests. + +**Use `console` language tag with `$ ` prefix.** This distinguishes interactive commands from scripts and enables prompt-aware copy in many terminals. + +Good: + +```console +$ uv run pytest +``` + +Bad: + +```bash +uv run pytest +``` + +**Split long commands with `\` for readability.** Each flag or flag+value pair gets its own continuation line, indented. Positional parameters go on the final line. + +Good: + +```console +$ pipx install \ + --suffix=@next \ + --pip-args '\--pre' \ + --force \ + 'libtmux' +``` + +Bad: + +```console +$ pipx install --suffix=@next --pip-args '\--pre' --force 'libtmux' +``` + ## Debugging Tips When stuck in debugging loops: From 876c30c0323aa05ea381531933d260b8ec064ba5 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 14 Mar 2026 18:58:52 -0500 Subject: [PATCH 2/3] docs(style[shell]): Standardize shell code blocks in docs why: Improve copy-pastability and readability of shell examples what: - Ensure all shell blocks use console tag with $ prefix - Split multi-command blocks into one command per block - Split wide multi-flag commands with \ line continuations - Fix README.md, docs/quickstart.md, docs/developing.md --- README.md | 24 +++++++++++++++--------- docs/developing.md | 28 ++++++++++++++++++++++------ docs/quickstart.md | 14 +++++++++++--- 3 files changed, 48 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 1d3dc7770..0944eea4e 100644 --- a/README.md +++ b/README.md @@ -41,27 +41,30 @@ Maintenance-only backports (no new fixes): Stable release: -```bash -pip install libtmux +```console +$ pip install libtmux ``` With pipx: -```bash -pipx install libtmux +```console +$ pipx install libtmux ``` With uv / uvx: -```bash -uv add libtmux -uvx --from "libtmux" python +```console +$ uv add libtmux +``` + +```console +$ uvx --from "libtmux" python ``` From the main branch (bleeding edge): -```bash -pip install 'git+https://github.com/tmux-python/libtmux.git' +```console +$ pip install 'git+https://github.com/tmux-python/libtmux.git' ``` Tip: libtmux is pre-1.0. Pin a range in projects to avoid surprises: @@ -94,6 +97,9 @@ Use [ptpython], [ipython], etc. for a nice REPL with autocompletions: ```console $ pip install --user ptpython +``` + +```console $ ptpython ``` diff --git a/docs/developing.md b/docs/developing.md index dcafc1f16..c563fd2f7 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -73,8 +73,7 @@ $ make start ### Manual documentation (the hard way) ```console -$ cd docs/ -$ make html +$ cd docs/ && make html ``` to build. @@ -86,8 +85,16 @@ $ make serve to start http server. Helpers: + +Build docs: + ```console $ make build_docs +``` + +Serve docs: + +```console $ make serve_docs ``` @@ -278,10 +285,19 @@ building, and publishing. Therefore there is no setup.py or requirements files. Update `__version__` in `__about__.py` and `pyproject.toml`: ```console -git commit -m 'build(libtmux): Tag v0.1.1' -git tag v0.1.1 -git push -git push --tags +$ git commit -m 'build(libtmux): Tag v0.1.1' +``` + +```console +$ git tag v0.1.1 +``` + +```console +$ git push +``` + +```console +$ git push --tags ``` [twine]: https://twine.readthedocs.io/ diff --git a/docs/quickstart.md b/docs/quickstart.md index 39b11aa70..82f996ca7 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -44,10 +44,15 @@ the 4th beta release of `1.10.0` before general availability. - [pipx]\: ```console - $ pipx install --suffix=@next 'libtmux' --pip-args '\--pre' --force - // Usage: libtmux@next [command] + $ pipx install \ + --suffix=@next \ + --pip-args '\--pre' \ + --force \ + 'libtmux' ``` + Usage: `libtmux@next [command]` + - [uv tool install][uv-tools]\: ```console @@ -77,7 +82,10 @@ via trunk (can break easily): - [pipx]\: ```console - $ pipx install --suffix=@master 'libtmux @ git+https://github.com/tmux-python/libtmux.git@master' --force + $ pipx install \ + --suffix=@master \ + --force \ + 'libtmux @ git+https://github.com/tmux-python/libtmux.git@master' ``` - [uv]\: From 0b185f762b1aca7f442869a47b5364a879e42f50 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 15 Mar 2026 05:10:40 -0500 Subject: [PATCH 3/3] docs(style[shell]): Split long commands with line continuations why: Apply the line-splitting rule from Shell Command Formatting guidelines what: - Split pipx install command in CHANGES header --- CHANGES | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 08a35474d..70cecc49a 100644 --- a/CHANGES +++ b/CHANGES @@ -12,7 +12,11 @@ $ pip install --user --upgrade --pre libtmux [pipx](https://pypa.github.io/pipx/docs/): ```console -$ pipx install --suffix=@next 'libtmux' --pip-args '\--pre' --force +$ pipx install \ + --suffix=@next \ + --pip-args '\--pre' \ + --force \ + 'libtmux' // Usage: libtmux@next [command] ```