diff --git a/CHANGES b/CHANGES index 02c17749d..0e9117ee8 100644 --- a/CHANGES +++ b/CHANGES @@ -40,6 +40,11 @@ $ uvx --from 'libtmux' --prerelease allow python _Notes on the upcoming release will go here._ +### Documentation + +- Visual improvements to API docs from [gp-sphinx](https://gp-sphinx.git-pull.com)-based Sphinx packages (#658) + + ### What's new #### pytest plugin: fixture reference documentation with autofixture directives (#656) diff --git a/docs/conf.py b/docs/conf.py index 09e1c28de..e902a2398 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,7 +30,11 @@ source_branch="master", light_logo="img/libtmux.svg", dark_logo="img/libtmux.svg", - extra_extensions=["sphinx_autodoc_pytest_fixtures", "sphinx.ext.todo"], + extra_extensions=[ + "sphinx_autodoc_api_style", + "sphinx_autodoc_pytest_fixtures", + "sphinx.ext.todo", + ], intersphinx_mapping={ "python": ("https://docs.python.org/", None), "pytest": ("https://docs.pytest.org/en/stable/", None), diff --git a/pyproject.toml b/pyproject.toml index f320d2d47..5821da39e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,8 +52,9 @@ Changes = "https://github.com/tmux-python/libtmux/blob/master/CHANGES" [dependency-groups] dev = [ # Docs (via gp-sphinx) - "gp-sphinx==0.0.1a1", - "sphinx-autodoc-pytest-fixtures==0.0.1a1", + "gp-sphinx==0.0.1a7", + "sphinx-autodoc-api-style==0.0.1a7", + "sphinx-autodoc-pytest-fixtures==0.0.1a7", "sphinx-autobuild", "types-docutils", # Testing @@ -74,8 +75,9 @@ dev = [ ] docs = [ - "gp-sphinx==0.0.1a1", - "sphinx-autodoc-pytest-fixtures==0.0.1a1", + "gp-sphinx==0.0.1a7", + "sphinx-autodoc-api-style==0.0.1a7", + "sphinx-autodoc-pytest-fixtures==0.0.1a7", "sphinx-autobuild", ] testing = [ diff --git a/uv.lock b/uv.lock index fb765647e..798bade62 100644 --- a/uv.lock +++ b/uv.lock @@ -393,7 +393,7 @@ wheels = [ [[package]] name = "gp-sphinx" -version = "0.0.1a1" +version = "0.0.1a7" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "docutils" }, @@ -414,9 +414,9 @@ dependencies = [ { name = "sphinxext-opengraph" }, { name = "sphinxext-rediraffe" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/23/89/aa7d03025bbcd036806a67299f04c1de302eda265b35046a1355240503da/gp_sphinx-0.0.1a1.tar.gz", hash = "sha256:70f99cdd2ef5f24aa160da4eb47f80933c8d69bce00383dc0eb60e8bd51663f5", size = 13991, upload-time = "2026-04-05T17:32:41.295Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ed/04/c82ff029d74e0b0bf3e9ea29ec33af8036b07697ab9c5d96fd73ade46f38/gp_sphinx-0.0.1a7.tar.gz", hash = "sha256:c7eea8e35034a194848bb9102776aa11559a3545883f478f3c09b1a9beee06a4", size = 13992, upload-time = "2026-04-11T13:17:01.328Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/a3/2a/21836581ec988b8c58cacac2bfb091bbb000b8fe682f62a2fa584674aa6b/gp_sphinx-0.0.1a1-py3-none-any.whl", hash = "sha256:6f0c73a1a13ba94bef7fb1c5368fe6e47dc4128ec948c27f08e834cdf41a2111", size = 14398, upload-time = "2026-04-05T17:32:31.292Z" }, + { url = "https://files.pythonhosted.org/packages/c7/6b/01d8ab2777abeb83c34c9ddd1a8eea0f49d68c3ed95502ed50e666c71bcf/gp_sphinx-0.0.1a7-py3-none-any.whl", hash = "sha256:c8fda26b6a7213c4774449380059937f28b8e57190474fe2a2f691663a0b5212", size = 14411, upload-time = "2026-04-11T13:16:46.317Z" }, ] [[package]] @@ -578,6 +578,7 @@ dev = [ { name = "ruff" }, { name = "sphinx-autobuild", version = "2024.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autobuild", version = "2025.8.25", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-autodoc-api-style" }, { name = "sphinx-autodoc-pytest-fixtures" }, { name = "types-docutils" }, { name = "typing-extensions", marker = "python_full_version < '3.11'" }, @@ -586,6 +587,7 @@ docs = [ { name = "gp-sphinx" }, { name = "sphinx-autobuild", version = "2024.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autobuild", version = "2025.8.25", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-autodoc-api-style" }, { name = "sphinx-autodoc-pytest-fixtures" }, ] lint = [ @@ -614,7 +616,7 @@ dev = [ { name = "codecov" }, { name = "coverage" }, { name = "gp-libs" }, - { name = "gp-sphinx", specifier = "==0.0.1a1" }, + { name = "gp-sphinx", specifier = "==0.0.1a7" }, { name = "mypy" }, { name = "pytest" }, { name = "pytest-cov" }, @@ -624,14 +626,16 @@ dev = [ { name = "pytest-xdist" }, { name = "ruff" }, { name = "sphinx-autobuild" }, - { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a1" }, + { name = "sphinx-autodoc-api-style", specifier = "==0.0.1a7" }, + { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a7" }, { name = "types-docutils" }, { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] docs = [ - { name = "gp-sphinx", specifier = "==0.0.1a1" }, + { name = "gp-sphinx", specifier = "==0.0.1a7" }, { name = "sphinx-autobuild" }, - { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a1" }, + { name = "sphinx-autodoc-api-style", specifier = "==0.0.1a7" }, + { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a7" }, ] lint = [ { name = "mypy" }, @@ -1271,18 +1275,46 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d7/20/56411b52f917696995f5ad27d2ea7e9492c84a043c5b49a3a3173573cd93/sphinx_autobuild-2025.8.25-py3-none-any.whl", hash = "sha256:b750ac7d5a18603e4665294323fd20f6dcc0a984117026d1986704fa68f0379a", size = 12535, upload-time = "2025-08-25T18:44:54.164Z" }, ] +[[package]] +name = "sphinx-autodoc-api-style" +version = "0.0.1a7" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-autodoc-badges" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a2/ba/ac334df39fe2f25f7d5aa5bfc3cfe3ff1cda611f233bcd12118809fba564/sphinx_autodoc_api_style-0.0.1a7.tar.gz", hash = "sha256:8860616f0af7c8bfd340f65008c994e30bbf73a6fd3d851b3f181fceb664580a", size = 10923, upload-time = "2026-04-11T13:17:03.439Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e8/a3/ffb88b803d88374d2a0a361c5b82819a6e0fcbeebe16d368f81750dbc7a5/sphinx_autodoc_api_style-0.0.1a7-py3-none-any.whl", hash = "sha256:4627a148bab6889a0e2ec1b93c4ab12ee0438f04d6c8fbc350eda5c571f531cc", size = 11475, upload-time = "2026-04-11T13:16:49.713Z" }, +] + +[[package]] +name = "sphinx-autodoc-badges" +version = "0.0.1a7" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f8/23/561cf78ae0b5891cf6722f749c36caaf656aa64b481b37a121414ac890d7/sphinx_autodoc_badges-0.0.1a7.tar.gz", hash = "sha256:7aa04ad728d59023b65a174512497915bc2a9ab6d3160457c4a709ba88d31666", size = 8044, upload-time = "2026-04-11T13:17:04.542Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/43/6f/0c8100492c8567a6e1cd93b76834387e86947eda4e152357798d389d9c61/sphinx_autodoc_badges-0.0.1a7-py3-none-any.whl", hash = "sha256:902f5618cbec522f7aaad64c4fc613238bc3e9faa6085091000adc41eb95aa4d", size = 8365, upload-time = "2026-04-11T13:16:51.268Z" }, +] + [[package]] name = "sphinx-autodoc-pytest-fixtures" -version = "0.0.1a1" +version = "0.0.1a7" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "pytest" }, { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-autodoc-badges" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/ed/1f/d70118d2b81863a934a204ea889bf22bfe08a95ef57016fa8035a9e0a9ee/sphinx_autodoc_pytest_fixtures-0.0.1a1.tar.gz", hash = "sha256:a6424d1a56d243886b0d78eb12b743b2449d3b1af0d0687c20e70aae010a6f26", size = 35118, upload-time = "2026-04-05T17:32:44.87Z" } +sdist = { url = "https://files.pythonhosted.org/packages/b2/1e/ab37d561d2f9f221684ad9b2d7465ad9d906a1e8d92290dddca724f68d12/sphinx_autodoc_pytest_fixtures-0.0.1a7.tar.gz", hash = "sha256:81e05927f6bde3a39e3881c10480bb2a11ac32a92f26d5f06c0986abbd58b456", size = 36899, upload-time = "2026-04-11T13:17:07.631Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/0b/36/7aa6d743db7f4dfa606c87637a4b521a64d833d9d6394ee72692db9ca03e/sphinx_autodoc_pytest_fixtures-0.0.1a1-py3-none-any.whl", hash = "sha256:02759731fe70ccbb5b357b4e2afd1ce0c63fb99be28237f9d125b484c1a37cc7", size = 42957, upload-time = "2026-04-05T17:32:35.88Z" }, + { url = "https://files.pythonhosted.org/packages/0b/d2/b773995562cfd3d3086ff716e6104dde9029134e704ad89d0051dd165cb5/sphinx_autodoc_pytest_fixtures-0.0.1a7-py3-none-any.whl", hash = "sha256:b9e298c1e8935c43e2b7f8b6fddac03a373201bd5048d4d822a36802f8bee6b5", size = 44378, upload-time = "2026-04-11T13:16:55.405Z" }, ] [[package]] @@ -1375,27 +1407,27 @@ wheels = [ [[package]] name = "sphinx-fonts" -version = "0.0.1a1" +version = "0.0.1a7" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/27/17/c7bdfd74248812b5d7df452d65474817ba96d41ebd67862022938c914465/sphinx_fonts-0.0.1a1.tar.gz", hash = "sha256:2c4ae152636649d88151a1421293b7b147bab36d97ef7aa3e85ce52ce7984dad", size = 5628, upload-time = "2026-04-05T17:32:46.905Z" } +sdist = { url = "https://files.pythonhosted.org/packages/f6/8a/ea86daed70e0039aace2b8143610efebc1f8ce949c365e3907b2a0f58092/sphinx_fonts-0.0.1a7.tar.gz", hash = "sha256:7da3f383a225b623d38c263b3e805620fd0d9b262aa1f3a66bc9bbac2ba44a0b", size = 5624, upload-time = "2026-04-11T13:17:09.822Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b5/dd/595ac1e9f72c7bc9b19bc9cc2e5c3d429c4d20b9a344674d23b75269906f/sphinx_fonts-0.0.1a1-py3-none-any.whl", hash = "sha256:6b45590254b912fb1b19e08c1ab6c3ce42eb1e1d07333183005d1fd54bb92b6f", size = 4348, upload-time = "2026-04-05T17:32:38.579Z" }, + { url = "https://files.pythonhosted.org/packages/b7/7c/a045b2021cc717cd474378e305e8df4f7b1a0971ef34096cbda8e0bd1c43/sphinx_fonts-0.0.1a7-py3-none-any.whl", hash = "sha256:68c109eb6a9b521e9d9105a08fd89b8dfd1012a058d9fcab49cfb05bd32eec11", size = 4348, upload-time = "2026-04-11T13:16:58.601Z" }, ] [[package]] name = "sphinx-gptheme" -version = "0.0.1a1" +version = "0.0.1a7" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "furo" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/b9/8d/2bbde808fcc5aadb2e9cdb4c5ae0713ad88f3f57bfbdcfc6f0a4eae82bb2/sphinx_gptheme-0.0.1a1.tar.gz", hash = "sha256:d4b64b6dd6f8c213300820e1300ba075c56428946f4a903d1258440c0a9094d5", size = 14566, upload-time = "2026-04-05T17:32:47.688Z" } +sdist = { url = "https://files.pythonhosted.org/packages/98/4d/277288688e242b96458ad79f07ce1a003c7d65b9f09c616337b799db8524/sphinx_gptheme-0.0.1a7.tar.gz", hash = "sha256:3b2dee7cdfe5206e0cd83d2ad9d0d44eb802fb0da4cc189b34a8d56ef9770ad6", size = 14569, upload-time = "2026-04-11T13:17:10.676Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b6/18/85b1d4550501d7f4a91d75a2ad39e6883e988e4217272e216e5a86b80a49/sphinx_gptheme-0.0.1a1-py3-none-any.whl", hash = "sha256:52a752136bda4641d001d8f32f59f3b492a631fe19cec116ba14c316351ba00d", size = 15624, upload-time = "2026-04-05T17:32:39.9Z" }, + { url = "https://files.pythonhosted.org/packages/ad/34/5a88f8f90fd7f70a89834b386be91f110bec12726e747e1c483cb1cccf50/sphinx_gptheme-0.0.1a7-py3-none-any.whl", hash = "sha256:fc2c61d96e3a65c628ed0bc62b414d7cc69089a5be8873f500e6c8ef1a833cc0", size = 15628, upload-time = "2026-04-11T13:17:00.123Z" }, ] [[package]]