diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d43d6114..2bd56b53 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,6 +4,8 @@ on: push: branches: - master + # TEMP: remove after merge — publish docs from this branch for preview + - api-styling permissions: contents: read diff --git a/docs/conf.py b/docs/conf.py index 370165c3..11289c1d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,7 @@ light_logo="img/libvcs.svg", dark_logo="img/libvcs-dark.svg", extra_extensions=[ + "sphinx_autodoc_api_style", "sphinx.ext.todo", "sphinx_autodoc_pytest_fixtures", ], diff --git a/pyproject.toml b/pyproject.toml index 41886dbe..b64792e8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,8 +64,9 @@ Changes = "https://github.com/vcs-python/libvcs/blob/master/CHANGES" [dependency-groups] dev = [ # Docs - "gp-sphinx==0.0.1a3", - "sphinx-autodoc-pytest-fixtures==0.0.1a3", + "gp-sphinx==0.0.1a6", + "sphinx-autodoc-api-style==0.0.1a6", + "sphinx-autodoc-pytest-fixtures==0.0.1a6", "gp-libs", "sphinx-autobuild", # Testing @@ -84,8 +85,9 @@ dev = [ ] docs = [ - "gp-sphinx==0.0.1a3", - "sphinx-autodoc-pytest-fixtures==0.0.1a3", + "gp-sphinx==0.0.1a6", + "sphinx-autodoc-api-style==0.0.1a6", + "sphinx-autodoc-pytest-fixtures==0.0.1a6", "gp-libs", "sphinx-autobuild", ] diff --git a/uv.lock b/uv.lock index 87884b92..5dd1798e 100644 --- a/uv.lock +++ b/uv.lock @@ -384,7 +384,7 @@ wheels = [ [[package]] name = "gp-sphinx" -version = "0.0.1a3" +version = "0.0.1a6" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "docutils" }, @@ -405,9 +405,9 @@ dependencies = [ { name = "sphinxext-opengraph" }, { name = "sphinxext-rediraffe" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1f/a3/d6c953e2f1e3d897d0c25886b9ecf9ad2d798c243397d747e899b3c9b115/gp_sphinx-0.0.1a3.tar.gz", hash = "sha256:c526a563eb56f89960a86669ba586f4871c7fed68a148697f820fdde7dbc1715", size = 13997, upload-time = "2026-04-06T14:55:15.704Z" } +sdist = { url = "https://files.pythonhosted.org/packages/00/84/8bb79a1a7c3fb8da69c8afb776837cf0ac3fa8044ba79687daf30b1b101e/gp_sphinx-0.0.1a6.tar.gz", hash = "sha256:b0f8c9a9a49e5484523e3a9eb4776739a8724831b4912b61540ef6964d0a0478", size = 13993, upload-time = "2026-04-07T01:39:54.402Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/5d/2c/26a47e1abbc995c495976b341b321dc639c53667690ac534dfbef5971cd2/gp_sphinx-0.0.1a3-py3-none-any.whl", hash = "sha256:ba0579bcd0fc0a893042f7e96b1925fb05c36cc6da84c7774b6c64c7e199c436", size = 14403, upload-time = "2026-04-06T14:55:06.214Z" }, + { url = "https://files.pythonhosted.org/packages/12/15/04e2ebcaf8a19af509bc09f75fcfe14121a4201dc357d982e3b9b839dd82/gp_sphinx-0.0.1a6-py3-none-any.whl", hash = "sha256:c3021eab95e88fc29b3c08c183523d18c458abd2fbef2163e1e3938527d201a5", size = 14408, upload-time = "2026-04-07T01:36:41.362Z" }, ] [[package]] @@ -571,6 +571,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" }, ] docs = [ @@ -578,6 +579,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 = [ @@ -605,7 +607,7 @@ dev = [ { name = "codecov" }, { name = "coverage" }, { name = "gp-libs" }, - { name = "gp-sphinx", specifier = "==0.0.1a3" }, + { name = "gp-sphinx", specifier = "==0.0.1a6" }, { name = "mypy" }, { name = "pytest" }, { name = "pytest-cov" }, @@ -614,13 +616,15 @@ dev = [ { name = "pytest-watcher" }, { name = "ruff" }, { name = "sphinx-autobuild" }, - { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a3" }, + { name = "sphinx-autodoc-api-style", specifier = "==0.0.1a6" }, + { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a6" }, ] docs = [ { name = "gp-libs" }, - { name = "gp-sphinx", specifier = "==0.0.1a3" }, + { name = "gp-sphinx", specifier = "==0.0.1a6" }, { name = "sphinx-autobuild" }, - { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a3" }, + { name = "sphinx-autodoc-api-style", specifier = "==0.0.1a6" }, + { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.0.1a6" }, ] lint = [ { name = "mypy" }, @@ -1245,18 +1249,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.1a6" +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/fd/74/725982d1e1c96441812ba4bafb962fb12dae03dc48bd4dae7ebb53913791/sphinx_autodoc_api_style-0.0.1a6.tar.gz", hash = "sha256:cdac8845321853e920c1e702ed221b85af841b6906b0a4c161f5ded42da0254f", size = 10923, upload-time = "2026-04-07T01:39:56.417Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d2/79/ab4332c04261393766646a45c707b5eb4e258ba993db0ce0e96c0b36027e/sphinx_autodoc_api_style-0.0.1a6-py3-none-any.whl", hash = "sha256:c2aea727076e566cac279be8877f8cb8d41bbc78e91730ec4b026d5e20afcd88", size = 11475, upload-time = "2026-04-07T01:36:44.336Z" }, +] + +[[package]] +name = "sphinx-autodoc-badges" +version = "0.0.1a6" +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/aa/b4/95d4cf03ad5b80e24024b74a105cc3509f59f3923368f1c41480dea0c65f/sphinx_autodoc_badges-0.0.1a6.tar.gz", hash = "sha256:40883c7b4c0b250e7e9774b4bfa42c84703ce4375d23e24b6c2c38cd320e5ff6", size = 8042, upload-time = "2026-04-07T01:39:57.274Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/52/80/6e3fe1f7e65e218a534a9bcaf11394f30cba213c6dfc4de406f3b0d21ff7/sphinx_autodoc_badges-0.0.1a6-py3-none-any.whl", hash = "sha256:10718d58c8436a3b6855c39b83f4a149c6fcc26e3bc652ccecb5b9f8e5a0e7f3", size = 8365, upload-time = "2026-04-07T01:36:45.779Z" }, +] + [[package]] name = "sphinx-autodoc-pytest-fixtures" -version = "0.0.1a3" +version = "0.0.1a6" 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/03/0d/a9000567da2a9b441a98e21e10519a3d41717d79a420cb5f54d531679b82/sphinx_autodoc_pytest_fixtures-0.0.1a3.tar.gz", hash = "sha256:a45a2d321476cc71551bdc55fe8ef06ef6df70489d09ad7810629dc6d3ff04d0", size = 37978, upload-time = "2026-04-06T14:55:18.597Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ac/cf/2974e9ea5c213a6022d3455606984b7c49220dc95b4b10adf860cf441b4e/sphinx_autodoc_pytest_fixtures-0.0.1a6.tar.gz", hash = "sha256:26e8d7d12e463f22cec90566db2ae86c9cb6cfe8017d7dbdaf08a3c81e32489b", size = 36897, upload-time = "2026-04-07T01:40:00.69Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/c3/45/3d3a3aa08e077ae13cd2b54665475105308e70650858e61df10fb9dc1f96/sphinx_autodoc_pytest_fixtures-0.0.1a3-py3-none-any.whl", hash = "sha256:53dfd5e3142c164bbdffa3d9a2d52e56e50751cbd34f9fbfbcc0423770061eae", size = 45639, upload-time = "2026-04-06T14:55:10.339Z" }, + { url = "https://files.pythonhosted.org/packages/fb/41/0aa42ebf8ea408496cfff859f618d52b4aa735f168a36c24da9623b83ba2/sphinx_autodoc_pytest_fixtures-0.0.1a6-py3-none-any.whl", hash = "sha256:3c5f711b6b955c07178b2ea1628a2794dd659ec60260a9619dd8e97ce8e5c7de", size = 44378, upload-time = "2026-04-07T01:39:49.728Z" }, ] [[package]] @@ -1349,27 +1381,27 @@ wheels = [ [[package]] name = "sphinx-fonts" -version = "0.0.1a3" +version = "0.0.1a6" 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/d5/5c/dc2a92154f7f2c613d22171a2a22129c5cf99e0b3c8831c538de156bf256/sphinx_fonts-0.0.1a3.tar.gz", hash = "sha256:e678eece61cbbd6d9b17e76d219ce9236fe74f9192d5b48131acb5db03aefaa1", size = 5625, upload-time = "2026-04-06T14:55:20.301Z" } +sdist = { url = "https://files.pythonhosted.org/packages/68/4e/acac834c6244c4d7cf0ddd191fa70bdbaa5497c51205e77da99f697b2d64/sphinx_fonts-0.0.1a6.tar.gz", hash = "sha256:e8f2e6461998ab27f1603b8f32824e11ef690568d9b3e679fdb9d0389e26e197", size = 5626, upload-time = "2026-04-07T01:40:02.301Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/f3/fe/2e4be47ce74bb7d92e631baf46fef650e7a8411d6f78d6538d853d539720/sphinx_fonts-0.0.1a3-py3-none-any.whl", hash = "sha256:60e4ecd91e1b09bb55ef1ac6762ab68156048fb775e863e0ef01c2c8ee888111", size = 4348, upload-time = "2026-04-06T14:55:13.426Z" }, + { url = "https://files.pythonhosted.org/packages/ec/d9/cd9335becec5568fb1b8e1b58228bb0e09b3b37f543861bebd374dfecb64/sphinx_fonts-0.0.1a6-py3-none-any.whl", hash = "sha256:e6ec4866b7c8a13f5193c4adcf0d628a5f8683832d5239d75eee5bd909ae87f0", size = 4346, upload-time = "2026-04-07T01:39:52.244Z" }, ] [[package]] name = "sphinx-gptheme" -version = "0.0.1a3" +version = "0.0.1a6" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "furo" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/7a/d5/c7affb80d23c555b450ae3d30e9f6223958dacf4a86e49f9e916dcf5e384/sphinx_gptheme-0.0.1a3.tar.gz", hash = "sha256:619568ae8595fa7cfa093da8ebdc53bdc9f4ef6b02ea87dffb8f7e70797e4b73", size = 14567, upload-time = "2026-04-06T14:55:21.373Z" } +sdist = { url = "https://files.pythonhosted.org/packages/60/f3/1a5e65c3c8c5d7e0c461a2ae6b6ee657713cb91330bf79f061f6f0678b5a/sphinx_gptheme-0.0.1a6.tar.gz", hash = "sha256:50e3ca26db9130c319116d8276e83261a225d32a349966218404b339fc45589a", size = 14568, upload-time = "2026-04-07T01:40:03.366Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/d8/14/eddb972efb79a12eb34cc818a19fe3ab1f7a3f6aad31b72cb202860d7060/sphinx_gptheme-0.0.1a3-py3-none-any.whl", hash = "sha256:c65ef4a3b20044932579612ec0a0e16fa23a120ddf9e701128b87635c75dd707", size = 15626, upload-time = "2026-04-06T14:55:14.694Z" }, + { url = "https://files.pythonhosted.org/packages/b4/de/a5c9dabba700fe6dfaac4fb2a76b1f587f76179ca988e686a5b00b0f2be0/sphinx_gptheme-0.0.1a6-py3-none-any.whl", hash = "sha256:32bc5ee4daecf4ab2c187f9cacdee5824aca756d590d0d764827071ab92d8172", size = 15626, upload-time = "2026-04-07T01:39:53.351Z" }, ] [[package]]