From 7891472e85d8913972378e2415cd020a97490a50 Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Thu, 12 Nov 2026 15:38:20 +0100 Subject: [PATCH 1/3] style: switch to panache markdown formatting --- .panache.toml | 14 ++++++++++++++ .pre-commit-config.yaml | 5 +++++ .vscode/extensions.json | 1 + .vscode/settings.json | 7 +++++-- README.md | 6 +++--- biome.jsonc | 1 + docs/api/source.md | 12 ++++++------ docs/changelog.md | 1 - docs/contributing.md | 22 +++++----------------- docs/kitchen-sink.md | 20 ++++++++++++-------- tests/roots/minimal/index.md | 2 +- tests/roots/override/index.md | 2 +- 12 files changed, 54 insertions(+), 39 deletions(-) create mode 100644 .panache.toml diff --git a/.panache.toml b/.panache.toml new file mode 100644 index 0000000..ea38272 --- /dev/null +++ b/.panache.toml @@ -0,0 +1,14 @@ +#:schema https://panache.bz/panache.schema.json +flavor = "myst" + +[format] +wrap = "preserve" +smart-punctuation = "unicode" +tab-stops = "preserve" + +# MyST syntax extensions from `scverse_doc.config.MYST_ENABLE_EXTENSIONS` +[extensions] +myst-colon-fence = true # colon_fence +definition-lists = true # deflist +tex-math-dollars = true # dollarmath, amsmath +raw-html = true # html_image, html_admonition diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 51753b4..76ba025 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,6 +14,11 @@ repos: groups: [format] - id: biome-lint args: [--error-on-warnings] + - repo: https://github.com/jolars/panache-pre-commit + rev: v3.18.0 + hooks: + - id: panache-format + groups: [format] - repo: https://github.com/tox-dev/pyproject-fmt rev: v2.30.3 hooks: diff --git a/.vscode/extensions.json b/.vscode/extensions.json index caaeb4f..3e5224e 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -14,5 +14,6 @@ "editorconfig.editorconfig", "charliermarsh.ruff", "biomejs.biome", + "jolars.panache", ], } diff --git a/.vscode/settings.json b/.vscode/settings.json index a7380b5..06b108c 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,5 +1,5 @@ { - "[python][json][jsonc]": { + "[python][json][jsonc][yaml][markdown]": { "editor.formatOnSave": true, }, "[python]": { @@ -9,9 +9,12 @@ "source.organizeImports.ruff": "always", }, }, - "[json][jsonc]": { + "[json][jsonc][yaml]": { "editor.defaultFormatter": "biomejs.biome", }, + "[markdown]": { + "editor.defaultFormatter": "jolars.panache", + }, "python.testing.pytestEnabled": true, "python.testing.pytestArgs": ["-vv", "--color=yes"], "python-envs.defaultEnvManager": "pypa.hatch:hatch", diff --git a/README.md b/README.md index b0d0983..38b63fa 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ The shared Sphinx theme and documentation configuration for scverse packages. -Install it, and a package's `conf.py` becomes: +Install it, and a package’s `conf.py` becomes: ```python extensions = ["scverse_doc"] @@ -26,7 +26,7 @@ extensions = ["scverse_doc"] source_repository = "https://github.com/scverse/pertpy" ``` -That gets you the scverse brand and dark mode, the shared sidebar layout, footer, and announcement banner, a "scverse packages" dropdown generated from the package registry, cross-links to every core package, the repository links ("edit this page" and the header icon), and the standard extension stack. +That gets you the scverse brand and dark mode, the shared sidebar layout, footer, and announcement banner, a “scverse packages” dropdown generated from the package registry, cross-links to every core package, the repository links (“edit this page” and the header icon), and the standard extension stack. Every piece also works on its own. For the theme without the extension stack or the shared defaults, select it and leave `extensions` alone – it is a registered Sphinx theme, so installing the package is enough: @@ -45,7 +45,7 @@ The [kitchen sink][] shows every construct the theme styles, in both colour sche ## Installation You need to have Python 3.12 or newer installed on your system. -If you don't have Python installed, we recommend installing [uv][]. +If you don’t have Python installed, we recommend installing [uv][]. We recommend managing dependencies in project-specific virtual environments to avoid dependency conflicts. This is most convenient using package managers such as [uv][]. diff --git a/biome.jsonc b/biome.jsonc index 595b5b7..ac081e8 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -12,6 +12,7 @@ ], }, "formatter": { "useEditorconfig": true }, + "markdown": { "formatter": { "enabled": false } }, // handled by panache "javascript": { "formatter": { "semicolons": "asNeeded", diff --git a/docs/api/source.md b/docs/api/source.md index 6683d93..8dc5b88 100644 --- a/docs/api/source.md +++ b/docs/api/source.md @@ -52,12 +52,12 @@ An unknown forge still gets the icon link, just no per-page links. ## What each theme gets -| Theme | Reads | -| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `pydata-sphinx-theme`, and so {doc}`ours ` | `html_context`’s `{provider}_user`/`_repo`/`_version`/`_url` and `doc_path`, plus `use_edit_page_button` | -| `sphinx_rtd_theme` | the same, plus `display_{provider}`, `{provider}_host` and `conf_py_path` | -| `furo`, and anything else on `sphinx-basic-ng` | the `source_repository`/`source_branch`/`source_directory` theme options, plus `display_{provider}` for its footer icon – which it shows on Read the Docs only | -| `sphinx-book-theme` | the `repository_url`/`repository_branch`/`repository_provider`/`path_to_docs` theme options, plus `use_repository_button`, `use_source_button` and `use_issues_button` | + | Theme | Reads | + | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `pydata-sphinx-theme`, and so {doc}`ours ` | `html_context`’s `{provider}_user`/`_repo`/`_version`/`_url` and `doc_path`, plus `use_edit_page_button` | + | `sphinx_rtd_theme` | the same, plus `display_{provider}`, `{provider}_host` and `conf_py_path` | + | `furo`, and anything else on `sphinx-basic-ng` | the `source_repository`/`source_branch`/`source_directory` theme options, plus `display_{provider}` for its footer icon – which it shows on Read the Docs only | + | `sphinx-book-theme` | the `repository_url`/`repository_branch`/`repository_provider`/`path_to_docs` theme options, plus `use_repository_button`, `use_source_button` and `use_issues_button` | Only the options a theme declares are written; a theme that declares none of them – `alabaster`, say – is left alone. Anything `conf.py` set itself wins. diff --git a/docs/changelog.md b/docs/changelog.md index d9e79ba..66efc0f 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,3 +1,2 @@ ```{include} ../CHANGELOG.md - ``` diff --git a/docs/contributing.md b/docs/contributing.md index e6e9271..ce7dc6c 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -12,7 +12,6 @@ the [scientific Python tutorials][], or the [scanpy developer guide][]. [scanpy developer guide]: https://scanpy.scverse.org/page/dev/ :::{tip} The _hatch_ project manager - We highly recommend to familiarize yourself with [`hatch`][hatch]. Hatch is a Python project manager that @@ -23,14 +22,13 @@ Hatch is a Python project manager that While the project is setup with `hatch` in mind, it is still possible to use different tools to manage dependencies, such as `uv` or `pip`. - ::: [hatch]: https://hatch.pypa.io/latest/ ## Installing dev dependencies -In addition to the packages needed to _use_ this package, +In addition to the packages needed to *use* this package, you need additional python packages to [run tests](#writing-tests) and [build the documentation](#docs-building). :::::{tab-set} @@ -52,9 +50,9 @@ If you are using VS code, install the [hatch-code][] extension. Additionally, make sure that the `vscode-python-environments` extension is installed (should be by default) and `"python.useEnvironmentsExtension": true` is activated in your `settings.json`. -Next, open the "Python Environment Managers" sidebar. +Next, open the “Python Environment Managers” sidebar. You can do so by opening the command palette (Ctrl+Shift+P) and searching for `Python: Focus on Environment Managers View`. -It will show a collapsible list where you can expand "Hatch" +It will show a collapsible list where you can expand “Hatch” and activate an environment by clicking on the checkmark next to it. As the main development environment, we recommend to use `hatch-test` with the latest supported Python version. @@ -100,8 +98,6 @@ hatch env find hatch-test.py3.14-stable ``` and manually point it to the python binary. - - :::: ::::{tab-item} uv @@ -121,7 +117,6 @@ uv sync --all-extras ``` The `.venv` directory is typically automatically discovered by IDEs such as VS Code. - :::: ::::{tab-item} Pip @@ -138,7 +133,6 @@ pip install -e ".[dev,test,doc]" ``` The `.venv` directory is typically automatically discovered by IDEs such as VS Code. - :::: ::::: @@ -167,7 +161,7 @@ If you didn’t run the checks locally, the `Pre-commit checks` job of the GitHu pushes the automatic fixes back to your branch, and reports any remaining failures. We strongly encourage installing and running the checks locally first to understand their usage. -Finally, most editors have an _autoformat on save_ feature. +Finally, most editors have an *autoformat on save* feature. Consider enabling this option for [ruff][ruff-editors] and [biome][biome-editors]. [prek]: https://prek.j178.dev/ @@ -196,7 +190,6 @@ hatch test # test with the highest supported Python version # or hatch test --all # test with all supported Python versions ``` - :::: ::::{tab-item} uv @@ -205,7 +198,6 @@ hatch test --all # test with all supported Python versions ```bash uv run pytest ``` - :::: ::::{tab-item} Pip @@ -215,7 +207,6 @@ uv run pytest source .venv/bin/activate pytest ``` - :::: ::::: @@ -252,7 +243,7 @@ Please adhere to [Semantic Versioning][semver], in brief > > Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. -Once you are done, commit and push your changes and navigate to the "Releases" page of this project on GitHub. +Once you are done, commit and push your changes and navigate to the “Releases” page of this project on GitHub. Specify `vX.X.X` as a tag name and create a release. For more information, see [managing GitHub releases][]. This will automatically create a git tag and trigger a Github workflow that creates a release on [PyPI][]. @@ -312,7 +303,6 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu hatch run docs:build hatch run docs:open ``` - :::: ::::{tab-item} uv @@ -323,7 +313,6 @@ cd docs uv run sphinx-build -M html . _build -W (xdg-)open _build/html/index.html ``` - :::: ::::{tab-item} Pip @@ -335,7 +324,6 @@ cd docs sphinx-build -M html . _build -W (xdg-)open _build/html/index.html ``` - :::: ::::: diff --git a/docs/kitchen-sink.md b/docs/kitchen-sink.md index d795f25..6d57a30 100644 --- a/docs/kitchen-sink.md +++ b/docs/kitchen-sink.md @@ -7,7 +7,7 @@ like on any other – switch the theme with the toggle in the page header. ## Text -Body copy with **bold**, _italic_, `inline literal` (the default role), an +Body copy with **bold**, *italic*, `inline literal` (the default role), an [external link](https://scverse.org), an [internal one](api.md), a footnote[^fn] and a cross-reference to {func}`~scverse_doc.registry.intersphinx`. @@ -40,10 +40,11 @@ custom property; H{sub}`2`O and x{sup}`2` also render. 2. Numbered Definition list -: Enabled through the `deflist` MyST extension. +: Enabled through the `deflist` MyST extension. Field and option lists and `hlist` are docutils-only, so they need `eval-rst`: + ```{eval-rst} :Field: A field list entry. :Another: A second one. @@ -62,11 +63,12 @@ Field and option lists and `hlist` are docutils-only, so they need `eval-rst`: * scvi-tools * squidpy ``` + ## Admonitions ```{note} -A note, in the theme's border and surface tokens. +A note, in the theme’s border and surface tokens. ``` ```{warning} @@ -188,11 +190,11 @@ third = "plain" ## Table -| Token | Role | -| ----------------------------------- | -------------------------------- | -| `--scverse-color-accent-text` | Links and text, contrast-checked | -| `--scverse-color-accent-decorative` | Underlines and surfaces | -| `--scverse-radius` | Shared component geometry | + | Token | Role | + | ----------------------------------- | -------------------------------- | + | `--scverse-color-accent-text` | Links and text, contrast-checked | + | `--scverse-color-accent-decorative` | Underlines and surfaces | + | `--scverse-radius` | Shared component geometry | ## Cards @@ -229,10 +231,12 @@ accent-driven parts of the theme, build with one: $ hatch run docs:build -D html_theme_options.accent=#de367b ``` + ```{button-link} https://scverse.org :color: primary A button ``` + ## Tabs diff --git a/tests/roots/minimal/index.md b/tests/roots/minimal/index.md index 1403792..3395e5a 100644 --- a/tests/roots/minimal/index.md +++ b/tests/roots/minimal/index.md @@ -1,6 +1,6 @@ # Minimal fixture -A fixture documentation tree used by the theme's own tests. +A fixture documentation tree used by the theme’s own tests. ```{toctree} :hidden: diff --git a/tests/roots/override/index.md b/tests/roots/override/index.md index ce7e44a..ae599c3 100644 --- a/tests/roots/override/index.md +++ b/tests/roots/override/index.md @@ -1,3 +1,3 @@ # Minimal fixture -A fixture documentation tree used by the theme's own tests. +A fixture documentation tree used by the theme’s own tests. From d4adc92689ffcd54ca923e4bb49824985745e353 Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Thu, 12 Nov 2026 16:59:12 +0100 Subject: [PATCH 2/3] style: use scverse_doc MyST extensions in panache config --- .panache.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.panache.toml b/.panache.toml index ea38272..cd9509d 100644 --- a/.panache.toml +++ b/.panache.toml @@ -11,4 +11,4 @@ tab-stops = "preserve" myst-colon-fence = true # colon_fence definition-lists = true # deflist tex-math-dollars = true # dollarmath, amsmath -raw-html = true # html_image, html_admonition +raw-html = true # html_image, html_admonition From 9028624269df1ead9f77d9cab71b0c17a0c70303 Mon Sep 17 00:00:00 2001 From: Phil Schaf Date: Thu, 12 Nov 2026 18:01:35 +0100 Subject: [PATCH 3/3] style: drop unneeded panache ignore comments --- docs/kitchen-sink.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/kitchen-sink.md b/docs/kitchen-sink.md index 6d57a30..02e0550 100644 --- a/docs/kitchen-sink.md +++ b/docs/kitchen-sink.md @@ -231,12 +231,11 @@ accent-driven parts of the theme, build with one: $ hatch run docs:build -D html_theme_options.accent=#de367b ``` - ```{button-link} https://scverse.org :color: primary + A button ``` - ## Tabs