docs: lead topic pages with the concept, add docs voice guide#696
Merged
Conversation
why: The docs/ prose voice (concept before configuration, reader addressed directly, advanced parts marked opt-in) lived only in one page's git history. what: - Add docs/AGENTS.md describing the docs/ prose voice and audience, scoped as a complement to the root AGENTS.md - Exclude AGENTS.md from the Sphinx build so it is not an orphan doc
why: Claude Code reads CLAUDE.md; the symlink lets it pick up the same docs/ voice guidance without a second copy to keep in sync. what: - Symlink docs/CLAUDE.md -> AGENTS.md, mirroring the repository root - Exclude CLAUDE.md from the Sphinx build alongside AGENTS.md
why: These pages opened on a method signature or a flat "libtmux
provides X" and listed mechanics before the idea, so readers met the
API surface before learning what each operation does for them.
what:
- pane_interaction, context_managers, automation_patterns,
workspace_setup: concept-first leads, a "you can stop here"
reassurance, named trade-offs (tmux round-trips, stale objects
needing refresh(), polling cost), second-person present-tense voice,
and MyST cross-references at the point of curiosity
- Sentence-case page titles and lowercase section headings
- Convert the context_managers benefits/when-to-use bold enumerations
into prose
- Fix a pre-existing broken {ref}`context-managers` (the anchor is
context_managers) in automation_patterns
- Leave every doctest code block byte-identical; the executable spine
is unchanged
why: The navigation and query pages opened on mechanism — "libtmux uses QueryList", a target/format aside, a bare attribute list — before telling the reader what they were looking at or for. what: - traversal, filtering, clients, format-tokens: concept-first leads, a "you can stop here" reassurance, named trade-offs (each accessor re-queries tmux; refresh() round-trips; Python-side filter vs tmux-native search), and MyST cross-references at the point of curiosity - Sentence-case page titles and lowercase section headings (tmux stays lowercase as a proper noun) - Use the verified ~libtmux._internal.query_list paths for QueryList / ObjectDoesNotExist / MultipleObjectsReturned (QueryList is not exported at the top level) - Leave every doctest code block byte-identical
why: The options/hooks, floating-pane, and configuration pages led with the API surface or a terse one-liner instead of saying what the feature is and when a reader would reach for it. what: - options_and_hooks, floating_panes, configuration: concept-first leads, a "you can stop here" reassurance, named trade-offs (set/unset land live without refresh; remain-on-exit keeps a float on screen), and MyST cross-references at the point of curiosity - Reframe configuration (a stub) around "you configure libtmux entirely through Python", with the env-var and format-string layers as opt-in - Sentence-case page titles and lowercase section headings - Drop stray tool-call markup accidentally appended to floating_panes - Leave every doctest code block byte-identical
why: The architecture, design-decisions, and public-vs-internal pages opened on definitions and rationale before orienting the reader, with no signal that the material is reference they can skim or skip. what: - architecture, design-decisions, public-vs-internal: concept-first leads, an explicit "you don't need this to use the API" reassurance, named trade-offs (object snapshots go stale; format round-trips; two coexisting interfaces; internal imports carry no deprecation promise), and MyST cross-references at the point of curiosity - Sentence-case page titles and lowercase section headings - Leave every doctest code block byte-identical
why: An adversarial review against src/libtmux found prose claims that were factually wrong — invisible to doctests and the docs build, but misleading to readers. what: - architecture: drop the removed TmuxRelationalObject / TmuxMappingObject classes; describe the real mechanism (a shared Obj dataclass base in libtmux.neo; IDs stored as dataclass attributes) - workspace_setup: new_window() creates in the background by default (attach defaults to False), not active; re-reading a cached attribute needs refresh() to pick up external changes - configuration: libtmux does read LIBTMUX_TMUX_FORMAT_SEPARATOR, so stop claiming it reads no environment variables of its own - public-vs-internal: temper the stability promise (pre-1.0 minor versions may break; pin to a version); align the _internal list (sparse_array, not types) with the internals docs - pane_interaction: clear() runs `reset`, not `clear` - design-decisions: scope the round-trip cost to live collections; scalar fields are read once at build time - automation_patterns, clients, options_and_hooks, filtering: tighten imprecise wording and one cross-reference style
why: The file was copied verbatim from tmuxp, whose default reader writes YAML workspace files. libtmux's reader writes Python against the object API, so the audience, the framing, and the worked example all needed to change. what: - Rewrite the audience for the Python-writing reader (Server, Session, Window, Pane); "concept before configuration" becomes "concept before API surface" - Add an "Examples that run" section for libtmux's executed doctests: the doctest_namespace fixtures, python/console fences, and the load-bearing order of code blocks that share one doctest session - Add permission-granting framing and the Server -> Session -> Window -> Pane mental model to the voice - Point the worked example at docs/topics/pane_interaction.md - Note that just build-docs catches broken cross-references the doctests do not
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #696 +/- ##
=======================================
Coverage 51.89% 51.89%
=======================================
Files 25 25
Lines 3623 3623
Branches 733 733
=======================================
Hits 1880 1880
Misses 1439 1439
Partials 304 304 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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
1 participant
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.
The topics documentation now leads with the concept — what each object
or method is and does for the reader — before its API surface, with
reassurances that let a reader stop early and honest trade-offs where a
call costs something. A new docs-scoped voice guide codifies that voice
so future pages stay consistent.
voice for docs/ — a Python-writing reader, concept before API
surface, executable doctest examples, and MyST cross-references —
complementing the repository-root AGENTS.md. docs/CLAUDE.md symlinks
to it, and both are excluded from the Sphinx build so neither becomes
an orphan page.
with the idea before the signature, marks advanced and lower-level
material opt-in, names trade-offs (tmux round-trips, stale objects
needing refresh(), polling waits), and links classes and methods at
the point of curiosity. docs/topics/pane_interaction.md is the worked
example the guide points to.
creates a window in the background by default, clear() runs reset,
libtmux does read LIBTMUX_TMUX_FORMAT_SEPARATOR, the public API's
pre-1.0 stability story is stated honestly, and references to base
classes removed in 0.17 are gone.
cross-references only; every doctest code block stayed byte-identical,
so the page examples still execute under pytest and the docs build
stays clean.