docs(redesign): restructure documentation to Library Skeleton pattern#652
Merged
docs(redesign): restructure documentation to Library Skeleton pattern#652
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #652 +/- ##
=======================================
Coverage 51.19% 51.19%
=======================================
Files 25 25
Lines 2590 2590
Branches 402 402
=======================================
Hits 1326 1326
Misses 1094 1094
Partials 170 170 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
tony
force-pushed
the
2026-spring-doc-redesign
branch
from
da88fc9 to
030a5cb
Compare
…e URLs why: sphinx-design is needed for grid cards in the documentation landing pages and section indexes. Doc-site URLs added as inline comments for quick reference when managing dependencies. what: - Add sphinx-design to docs and dev dependency groups - Annotate all doc dependencies with their documentation URLs
why: The documentation had accumulated organically — test helpers and pytest plugin floated as top-level orphans, API reference files used ambiguous names (servers.md vs libtmux.server.md), internal APIs weren't separated from public ones, and the landing page dumped the full README with no navigation affordance. This restructure follows the Python Documentation Skeletons spec where api/ is the primary reference surface for a library package. what: Structure: - Rename api/ reference files to libtmux.<module>.md format (10 files) - Move test-helpers/ and pytest-plugin/ under api/ as auxiliary public API surfaces - Restructure internals/ with api/ subdirectory using libtmux._internal.*.md naming - Create project/ directory (contributing, code-style, releasing) - Move developing.md to project/contributing.md - Fold about.md content (ID prefixes, naming conventions) into topics/architecture.md New pages: - api/public-api.md — stability contract, pre-1.0 semver policy, deprecation process - api/compatibility.md — Python/tmux/platform support matrix - api/deprecations.md — active deprecation tracker - topics/architecture.md — module hierarchy, data flow, internal identifiers (merged from about.md) - topics/configuration.md — env vars, format handling - topics/design-decisions.md — ORM rationale, format strings, neo.py - topics/public-vs-internal.md — boundary philosophy, promotion path - project/code-style.md — ruff, mypy, NumPy docstrings - project/releasing.md — git tags, OIDC trusted publishing Landing page: - Compose standalone homepage (no README.md include) - One-sentence intro, 2x2 grid cards, 2-command install with pin tip, 6-line code snippet with hierarchy diagram, pytest fixture example Section indexes: - api/index.md: 2x2 Core Objects + 3x2 Supporting Modules card grids - topics/index.md: 2x4 card grid for substantive topic pages - project/index.md: 2x2 card grid for contributor pages Navigation: - Sidebar: Quickstart, Topics, API Reference, Internals, Project, Changelog, Migration, Glossary - 22 redirects for all renamed/moved files - README.md API URLs updated to new libtmux.<module>.html paths Dependencies: - Add sphinx-design to docs and dev dependency groups - Annotate all doc dependencies with documentation site URLs conf.py: - Add sphinx_design extension - Add myst_heading_anchors = 4
tony
force-pushed
the
2026-spring-doc-redesign
branch
from
030a5cb to
567111b
Compare
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.
Summary
Restructure libtmux documentation to follow the Library Documentation Skeleton pattern where
api/is the primary reference surface.libtmux.<module>.md, sectioned into Core Objects (2x2 cards) and Supporting Modules (3x2 cards). Test helpers and pytest plugin nested underapi/as auxiliary public surfaces.public-api.md(stability contract, pre-1.0 policy),compatibility.md(Python/tmux/platform matrix),deprecations.md(active deprecation tracker)internals/api/withlibtmux._internal.*.mdnaming, explicit instability warningTest plan
uv run sphinx-build -b html docs/ docs/_build/htmlbuilds without errorsuv run py.test docs/ README.mddoctests pass