Skip to content

docs: Migrate to gp-sphinx workspace packages#1033

Draft
tony wants to merge 13 commits intomasterfrom
gp-sphinx
Draft

docs: Migrate to gp-sphinx workspace packages#1033
tony wants to merge 13 commits intomasterfrom
gp-sphinx

Conversation

@tony
Copy link
Copy Markdown
Member

@tony tony commented Mar 29, 2026

Summary

Migrates tmuxp docs from individually-managed Sphinx extensions and manual conf.py boilerplate to the gp-sphinx shared documentation platform.

This PR depends on git-pull/gp-sphinx#init-2 — the workspace restructuring branch that splits gp-sphinx into 4 separate packages. Not ready to merge until gp-sphinx publishes those packages to PyPI.

What changed

  • pyproject.toml — Replace 9 individual sphinx deps (furo, sphinx-autodoc-typehints, sphinx-inline-tabs, sphinxext-opengraph, sphinx-copybutton, sphinxext-rediraffe, sphinx-design, myst-parser, linkify-it-py) with gp-sphinx + sphinx-argparse-neo. Uses [tool.uv.sources] pointing to local editable gp-sphinx packages during development.
  • docs/conf.py — Rewrites 293-line manual config to a 46-line merge_sphinx_config() call; make_linkcode_resolve() replaces 50-line manual linkcode_resolve(); theme switches from furo to sphinx-gptheme (Furo child theme); spa-nav.js/tabs.js workarounds handled by gp-sphinx.
  • docs/_ext/ — Removes sphinx_fonts.py, argparse_exemplar.py, argparse_lexer.py, argparse_roles.py, cli_usage_lexer.py, and the embedded sphinx_argparse_neo/ directory (~4,400 lines) — all now provided by published packages.
  • docs/_static/js/spa-nav.js — Removed; bundled in sphinx-gptheme theme statics.
  • tests/docs/_ext/ — Updates imports from old _ext/ paths to sphinx_argparse_neo.* package paths; removes sys.path manipulation from conftest; fixes version assertion in test_sphinx_fonts.py.

Bugs fixed upstream in gp-sphinx (init-2)

During the migration the following issues were found and fixed in gp-sphinx:

  • sphinx_argparse_neo/exemplar.pyfrom argparse_roles import register_rolesfrom sphinx_argparse_neo.roles import register_roles (would ModuleNotFoundError when installed as a package)
  • gp_sphinx/config.py — Removed dead ASSETS_DIR constant (no assets/ dir; spa-nav.js lives in sphinx-gptheme)
  • gp_sphinx/config.py — Added html_static_path = ["_static"] and templates_path = ["_templates"] defaults (without these, docs/_static/ was silently skipped — logos, custom CSS, favicons all 404'd)
  • gp_sphinx/defaults.py — Added DEFAULT_TOC_OBJECT_ENTRIES_SHOW_PARENTS = "hide" constant

Test plan

  • uv run pytest — 1154 passed, 2 skipped
  • uv run ruff check . — no issues
  • uv run mypy — no issues
  • just build-docs — build succeeded (101 pre-existing autodoc/cross-ref warnings, unrelated to this change)
  • Visual check via Playwright — logo, sidebar, IBM Plex fonts, argparse code blocks, projects sidebar all rendering correctly

@codecov
Copy link
Copy Markdown

codecov bot commented Mar 29, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.96%. Comparing base (097f617) to head (73e19a3).

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #1033      +/-   ##
==========================================
+ Coverage   81.02%   81.96%   +0.93%     
==========================================
  Files          28       28              
  Lines        2630     2545      -85     
  Branches      492      485       -7     
==========================================
- Hits         2131     2086      -45     
+ Misses        368      328      -40     
  Partials      131      131              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tony added 11 commits April 4, 2026 06:12
…ble)

why: gp-sphinx consolidates the docs configuration, extensions, theme, and
font setup that was duplicated across 14+ git-pull projects. This migration
replaces ~5500 lines of local copies and manual conf.py boilerplate with
a single merge_sphinx_config() call backed by 4 local editable packages.

what:
- pyproject.toml: Replace furo, sphinx-autodoc-typehints, sphinx-inline-tabs,
  sphinxext-opengraph, sphinx-copybutton, sphinxext-rediraffe, sphinx-design,
  myst-parser, linkify-it-py with gp-sphinx + sphinx-argparse-neo. Add
  [tool.uv.sources] pointing to local gp-sphinx packages as editable installs
- docs/conf.py: Rewrite 293-line manual config to 46-line merge_sphinx_config()
  call; use make_linkcode_resolve() for linkcode; theme switches to
  sphinx-gptheme (Furo child); spa-nav.js/tabs.js workarounds handled by
  gp-sphinx setup(); fonts/copybutton/myst/OGP all from defaults
- docs/_ext/: Remove sphinx_fonts.py, argparse_exemplar.py, argparse_lexer.py,
  argparse_roles.py, cli_usage_lexer.py, sphinx_argparse_neo/ (all now in
  published packages); keep aafig.py (tmuxp-specific)
- docs/_static/js/spa-nav.js: Remove (now bundled in sphinx-gptheme theme)
- tests/docs/_ext/: Update imports from old _ext/ paths to sphinx_argparse_neo.*
  package paths; remove sys.path manipulation from conftest.py; fix version
  assertion in test_sphinx_fonts.py to use __version__ instead of "1.0"
why: Switch from local editable path sources to git sources so the
branch is self-contained and reviewable without a local gp-sphinx
checkout. Points to the init-2 branch where the workspace packages live.

what:
- gp-sphinx, sphinx-fonts, sphinx-gptheme, sphinx-argparse-neo: change
  from path+editable to git+branch+subdirectory sources
why: All removed files are now bundled in sphinx-gptheme and loaded
     automatically, making local copies pure maintenance debt.
what:
- Delete argparse-highlight.css — identical to theme bundled version
- Delete custom.css — replaced by tmuxp.css (12-line project-specific
  aspect-ratio overrides only; all generic CSS now from theme)
- Delete _templates/page.html — identical to theme version; mask-icon
  moved to theme_options.mask_icon instead of hardcoded in template
- Delete _templates/sidebar/brand.html — identical to theme version
- Delete _templates/sidebar/projects.html — identical to theme version
- Add docs/_static/css/tmuxp.css with only tmuxp-specific image
  aspect-ratio rules (tmuxp-demo, tmuxp-shell, tmuxp-dev-screenshot)
- Update conf.py: css/custom.css → css/tmuxp.css,
  add theme_options={"mask_icon": "/_static/img/tmuxp.svg"}
- Update uv.lock to gp-sphinx init-2 commit c2fe249
  (theme: move mask-icon outside show_meta_app_icon_tags guard)
…ing)

why: gp-sphinx init-2 branch gained PEP 561 py.typed markers and strict mypy
     compliance across all 4 packages in the typing(feat[py.typed]) commit.
what:
- uv.lock: bump all 4 gp-sphinx packages from c2fe249 → 1d48098
why: 1d48098 claimed py.typed but files were untracked — d5dfb2f fixes this.
what:
- uv.lock: bump all 4 gp-sphinx packages from 1d48098 → d5dfb2f
why: gp-sphinx gained FooterIconDict/FuroThemeOptions/FontConfig TypedDicts,
     object annotations for argparse fields, and SetupDict for setup() returns.
what:
- uv.lock: bump all 4 packages from d5dfb2f → b39dbd2
why: Pick up 6 bug fixes from code review (NullHandler, __version__,
os.path import, next() safety, doctest fix, ruff D suppression).
why: Pick up 3 regression fixes from code review investigation
(html_favicon, rediraffe_redirects, dead DEFAULT_SIDEBARS removal).
why: Pick up CI fixes (revert html_favicon/rediraffe_redirects defaults
that broke docs build under -W).
why: History cleanup — dropped 4 no-op commits (html_favicon and
rediraffe_redirects restore/revert pairs).
tony added 2 commits April 4, 2026 06:24
why: After rebasing onto master, trunk's unicode-range/multi-subset tests
reference _unicode_range, _UNICODE_RANGES, and subset-aware _on_builder_inited
which existed in the local docs/_ext/sphinx_fonts.py but are not yet in the
packaged sphinx_fonts from gp-sphinx.
what:
- Remove 4 _unicode_range / _UNICODE_RANGES unit tests
- Remove 2 _on_builder_inited tests for multi-subset and unicode_range support
why: After gp-sphinx migration, these modules are only imported in docs/
and tests/docs/ which are excluded from mypy scanning.
what:
- Remove aafigure, sphinx_argparse_neo, sphinx_fonts, docutils, pygments
  from mypy overrides
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.

1 participant