From aa67de92bb25e47221cf83506c695211e5bda9f5 Mon Sep 17 00:00:00 2001 From: Samuel Hinton Date: Fri, 14 Nov 2025 09:17:43 +1000 Subject: [PATCH 1/4] Adding zensical note, and aligning order of docs between sphinx and mkdocs --- docs/pages/guides/docs.md | 56 ++++++++++++++++++++++-------------- docs/pages/tutorials/docs.md | 3 +- 2 files changed, 36 insertions(+), 23 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index c42a9a0b..7242cf9f 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -43,6 +43,17 @@ and Mkdocs, and uses the modern MyST plugin to get Markdown support. > collection of notebooks using Sphinx internally. Can also be used for docs, > though, see [echopype](https://echopype.readthedocs.io). + +{: .warning-title } + +> The Future of MkDocs +> +> The creators of `mkdocs-material` and `mkdocstrings` have come together +> to create a new documentation package called [Zensical](https://zensical.org/about/). +> The framework is still in alpha development, but aims to simplify the +> documentation process, be blazing fast, and move away from the limitations +> of MkDocs. + ## What to include Ideally, software documentation should include: @@ -83,6 +94,25 @@ and MkDocs diverge. {% tabs %}{% tab sphinx Sphinx %} +### pyproject.toml additions + +Setting a `docs` dependency group looks like this: + +```toml +[dependency-groups] +docs = [ + "furo", + "myst_parser >=0.13", + "sphinx >=4.0", + "sphinx-copybutton", + "sphinx-autodoc-typehints", +] +``` + +You should include the docs group via `--group=docs` when using uv or pip to install, +or install all groups, such as by running `uv sync --all-groups`. + + There is a sphinx-quickstart tool, but it creates unnecessary files (make/bat, we recommend a cross-platform noxfile instead), and uses rST instead of Markdown. Instead, this is our recommended starting point for `conf.py`: @@ -248,33 +278,13 @@ to mark where you want the docs portion to start. You can add the standard indices and tables at the end. -### pyproject.toml additions - -Setting a `docs` dependency group looks like this: - -```toml -[dependency-groups] -docs = [ - "furo", - "myst_parser >=0.13", - "sphinx >=4.0", - "sphinx-copybutton", - "sphinx-autodoc-typehints", -] -``` - -You should use `--group=docs` when using uv or pip to install. {% endtab %} {% tab mkdocs MkDocs %} While the cookie cutter creates a basic structure for your MkDocs (a top level `mkdocs.yml` file and the `docs` directory), you can also follow the official [Getting started](https://squidfunk.github.io/mkdocs-material/getting-started/) -guide instead. Note, however, instead of the `pip` install, it is better -practice install your documentation dependencies via `pyproject.toml` and then -when you run your `uv sync` to install dependencies, you can explicitly ask for -the `docs` group to be installed via `uv sync --group=docs` or -`uv sync --all-groups`. +guide instead. If you selected the `mkdocs` option when using the template cookie-cutter repository, you will already have this group. Otherwise, add to your @@ -292,6 +302,10 @@ docs = [ ] ``` +You should include the docs group via `--group=docs` when using uv or pip to install, +or install all groups, such as by running `uv sync --all-groups`. + + These dependencies include several common plugins---such as generating reference API documentation from docstrings---to make life easier. diff --git a/docs/pages/tutorials/docs.md b/docs/pages/tutorials/docs.md index 336aedd5..e6c78049 100644 --- a/docs/pages/tutorials/docs.md +++ b/docs/pages/tutorials/docs.md @@ -42,8 +42,7 @@ generator via [mkdocs-material][]. For more details, examples to help you pick between Sphinx and MkDocs (and instructions for the latter), see the [documentation guide][]. For this simple introduction, we will use Sphinx as it is still more popular with scientific -libraries, even though MkDocs is simpler to set up and more popular in general -with Python documentation. +libraries. Please refer to the MyST documentation for more information on the Markdown syntax in general and MyST's flavor of Markdown in particular. From 388c319f44d65fa59cdbdffad53cd79458c075fb Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 13 Nov 2025 23:23:39 +0000 Subject: [PATCH 2/4] style: pre-commit fixes --- docs/pages/guides/docs.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 7242cf9f..618b67f9 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -43,16 +43,15 @@ and Mkdocs, and uses the modern MyST plugin to get Markdown support. > collection of notebooks using Sphinx internally. Can also be used for docs, > though, see [echopype](https://echopype.readthedocs.io). - {: .warning-title } > The Future of MkDocs > -> The creators of `mkdocs-material` and `mkdocstrings` have come together -> to create a new documentation package called [Zensical](https://zensical.org/about/). -> The framework is still in alpha development, but aims to simplify the -> documentation process, be blazing fast, and move away from the limitations -> of MkDocs. +> The creators of `mkdocs-material` and `mkdocstrings` have come together to +> create a new documentation package called +> [Zensical](https://zensical.org/about/). The framework is still in alpha +> development, but aims to simplify the documentation process, be blazing fast, +> and move away from the limitations of MkDocs. ## What to include @@ -109,9 +108,8 @@ docs = [ ] ``` -You should include the docs group via `--group=docs` when using uv or pip to install, -or install all groups, such as by running `uv sync --all-groups`. - +You should include the docs group via `--group=docs` when using uv or pip to +install, or install all groups, such as by running `uv sync --all-groups`. There is a sphinx-quickstart tool, but it creates unnecessary files (make/bat, we recommend a cross-platform noxfile instead), and uses rST instead of @@ -278,13 +276,12 @@ to mark where you want the docs portion to start. You can add the standard indices and tables at the end. - {% endtab %} {% tab mkdocs MkDocs %} While the cookie cutter creates a basic structure for your MkDocs (a top level `mkdocs.yml` file and the `docs` directory), you can also follow the official [Getting started](https://squidfunk.github.io/mkdocs-material/getting-started/) -guide instead. +guide instead. If you selected the `mkdocs` option when using the template cookie-cutter repository, you will already have this group. Otherwise, add to your @@ -302,9 +299,8 @@ docs = [ ] ``` -You should include the docs group via `--group=docs` when using uv or pip to install, -or install all groups, such as by running `uv sync --all-groups`. - +You should include the docs group via `--group=docs` when using uv or pip to +install, or install all groups, such as by running `uv sync --all-groups`. These dependencies include several common plugins---such as generating reference API documentation from docstrings---to make life easier. From 0a497d3db662a7e2b1454a94d4fc21c251dec07e Mon Sep 17 00:00:00 2001 From: Samuel Hinton Date: Fri, 14 Nov 2025 14:08:55 +1000 Subject: [PATCH 3/4] Update docs/pages/guides/docs.md Co-authored-by: Henry Schreiner --- docs/pages/guides/docs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 618b67f9..5c573925 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -51,7 +51,9 @@ and Mkdocs, and uses the modern MyST plugin to get Markdown support. > create a new documentation package called > [Zensical](https://zensical.org/about/). The framework is still in alpha > development, but aims to simplify the documentation process, be blazing fast, -> and move away from the limitations of MkDocs. +> and move away from the limitations of MkDocs. This also means MkDocs's +> future is uncertain, and mkdocs-material will be minimally maintained +> until late 2026. ## What to include From c5aa64c635ddea12d61967a79f3195a9644dfbba Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 14 Nov 2025 04:09:15 +0000 Subject: [PATCH 4/4] style: pre-commit fixes --- docs/pages/guides/docs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 5c573925..bb38ef82 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -51,9 +51,9 @@ and Mkdocs, and uses the modern MyST plugin to get Markdown support. > create a new documentation package called > [Zensical](https://zensical.org/about/). The framework is still in alpha > development, but aims to simplify the documentation process, be blazing fast, -> and move away from the limitations of MkDocs. This also means MkDocs's -> future is uncertain, and mkdocs-material will be minimally maintained -> until late 2026. +> and move away from the limitations of MkDocs. This also means MkDocs's future +> is uncertain, and mkdocs-material will be minimally maintained until +> late 2026. ## What to include