feat: add an option to use Zensical

leodevian · leodevian · commit e063519857e4 · 2025-12-06T16:28:16.000+01:00
diff --git a/changelog.d/+fa4391ba.added.md b/changelog.d/+fa4391ba.added.md
@@ -0,0 +1 @@
+Add an option to use Zensical.
diff --git a/copier.yaml b/copier.yaml
@@ -190,6 +190,7 @@ docs:
   when: "{{ 'docs' in features }}"
   choices:
     MkDocs: mkdocs
+    Zensical: zensical
 
 doctest:
   type: str
diff --git a/template/.pre-commit-config.yaml.jinja b/template/.pre-commit-config.yaml.jinja
@@ -48,7 +48,7 @@ repos:
 {%- endif %}
         additional_dependencies:
           - mdformat-gfm
-{%- if docs == 'mkdocs' %}
+{%- if docs == 'mkdocs' or docs == 'zensical' %}
       - id: mdformat
         files: ^docs/
         additional_dependencies:
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
@@ -103,6 +103,12 @@ docs = [
   "mkdocs-material>=9.7",
   "mkdocstrings-python>=2",
 ]
+{%- elif docs == "zensical" %}
+docs = [
+  "black>=25.11",
+  "zensical>=0.0.11",
+  "mkdocstrings-python>=2",
+]
 {%- endif %}
 lint = [
   "pre-commit>=4.5",
diff --git a/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/changelog.md b/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/changelog.md
@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"
diff --git a/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/index.md.jinja b/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/index.md.jinja
@@ -0,0 +1,29 @@
+# {{ project_name }}
+
+[![PyPI](https://img.shields.io/pypi/v/{{ distribution_name }})](https://pypi.org/project/{{ distribution_name }}/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/{{ distribution_name }}?logo=python)](https://pypi.org/project/{{ distribution_name }}/)
+[![CI](https://img.shields.io/github/actions/workflow/status/{{ repository_path }}/ci.yaml?branch=main&logo=github&label=CI)](https://github.com/{{ repository_path }}/actions/workflows/ci.yaml)
+[![License](https://img.shields.io/github/license/{{ repository_path }})](https://github.com/{{ repository_path }}/blob/main/LICENSE)
+[![mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org)
+[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+{% if description %}
+{{ description }}.
+{% endif %}
+## Installation
+
+Install `{{ distribution_name }}` using [pip](https://pip.pypa.io/) or [uv](https://docs.astral.sh/uv/):
+
+```
+pip install {{ distribution_name }}
+```
+{% if cli %}
+## Execution
+
+Execute `{{ distribution_name }}` using [uvx](https://docs.astral.sh/uv/):
+
+```
+uvx {{ distribution_name }}
+```
+{% endif -%}
diff --git a/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/reference/api.md.jinja b/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/reference/api.md.jinja
@@ -0,0 +1,5 @@
+---
+title: API
+---
+
+# ::: {{ package_name }}
diff --git a/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/reference/index.md.jinja b/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/reference/index.md.jinja
@@ -0,0 +1,8 @@
+# Reference
+
+The reference section provides:
+
+- [API](./api.md): The reference for all classes, functions, parameters and attributes.
+{% if cli %}
+- [Commands](./cli.md): The reference for the command-line interface.
+{% endif -%}
diff --git a/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/reference/{% if cli %}cli.md{% endif %}.jinja b/template/{% if docs %}docs{% endif %}/{% if docs == 'zensical' %}.{% endif %}/reference/{% if cli %}cli.md{% endif %}.jinja
@@ -0,0 +1,11 @@
+# Commands
+
+## {{ distribution_name }}
+
+Run the main program.
+
+### Usage
+
+```
+{{ distribution_name }} [OPTIONS]
+```
diff --git a/template/{% if docs == 'zensical' %}zensical.toml{% endif %}.jinja b/template/{% if docs == 'zensical' %}zensical.toml{% endif %}.jinja
@@ -0,0 +1,81 @@
+[project]
+site_name = "{{ project_name }}"
+site_description = "{{ project_description }}"
+site_author = "{{ user_name }}"
+site_url = "{{ documentation_url }}/"
+copyright = "Copyright &copy; {{ copyright_year }} {{ copyright_owner }}"
+repo_url =  "{{ repository_url }}"
+repo_name = "{{ repository_path }}"
+edit_uri = "edit/main/docs/"
+
+[project.theme]
+features = [
+  "announce.dismiss",
+  "content.action.edit",
+  "content.action.view",
+  "content.code.annotate",
+  "content.code.copy",
+  "content.code.select",
+  "content.footnote.tooltips",
+  "content.tabs.link",
+  "content.tooltips",
+  "navigation.footer",
+  "navigation.indexes",
+  "navigation.instant",
+  "navigation.instant.prefetch",
+  "navigation.path",
+  "navigation.sections",
+  "navigation.tabs",
+  "navigation.tabs.sticky",
+  "navigation.top",
+  "navigation.tracking",
+  "search.highlight",
+  "toc.follow",
+]
+
+[[project.theme.palette]]
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+[project.theme.font]
+text = "Inter"
+code = "JetBrains Mono"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "{{ repository_url}}"
+
+[project.markdown_extensions]
+pymdownx.snippets = {}
+pymdownx.highlight = { anchor_linenums = true, pygments_lang_class = true }
+pymdownx.superfences = {}
+pymdownx.tabbed = { alternate_style = true }
+
+[project.plugins.mkdocstrings.handlers.python]
+inventories = [
+  "https://docs.python.org/3/objects.inv",
+]
+
+[project.plugins.mkdocstrings.handlers.python.options]
+parameter_headings = true
+show_root_heading = true
+show_symbol_type_heading = true
+show_symbol_type_toc = true
+type_parameter_headings = true
+inherited_members = true
+members_order = "source"
+summary = true
+docstring_style = "google"
+docstring_options = { ignore_init_summary = true }
+docstring_section_style = "table"
+merge_init_into_class = true
+show_signature_annotations = true
+show_signature_type_parameters = true
+separate_signature = true
+signature_crossrefs = true
diff --git a/template/{% if tasks == 'nox' %}noxfile.py{% endif %}.jinja b/template/{% if tasks == 'nox' %}noxfile.py{% endif %}.jinja
@@ -106,7 +106,7 @@ def typecheck(session: nox.Session) -> None:
 {%- endif %}
     session.run("mypy", *(session.posargs or ("src", "tests")))
 
-{% if docs == 'mkdocs' %}
+{% if docs %}
 @nox.session(python=DEFAULT_PYTHON_VERSION, tags=["checks"])
 def docs(session: nox.Session) -> None:
     """Build the documentation."""
@@ -116,6 +116,7 @@ def docs(session: nox.Session) -> None:
     uv_sync("--group", "docs", session=session)
 {%- endif %}
     tmp_dir = Path(session.create_tmp())
+{%- if docs == 'mkdocs' %}
     session.run(
         "mkdocs",
         "build",
@@ -125,7 +126,15 @@ def docs(session: nox.Session) -> None:
         tmp_dir,
         *session.posargs,
     )
-
+{%- elif docs == 'zensical' %}
+    session.run(
+        "zensical",
+        "build",
+        "--clean",
+        "--strict",
+        *session.posargs,
+    )
+{%- endif %}
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def autodocs(session: nox.Session) -> None:
@@ -135,12 +144,21 @@ def autodocs(session: nox.Session) -> None:
 {%- else %}
     uv_sync("--group", "docs", session=session)
 {%- endif %}
+{%- if docs == 'mkdocs' %}
     session.run(
         "mkdocs",
         "serve",
         "--open",
         *session.posargs,
     )
+{%- elif docs == 'zensical' %}
+    session.run(
+        "zensical",
+        "serve",
+        "--open",
+        *session.posargs,
+    )
+{%- endif %}
 
 {% endif %}{% if install == 'uv sync' %}
 def uv_sync(*args: str, session: nox.Session) -> None:
diff --git a/template/{% if tasks == 'tox' %}tox.toml{% endif %}.jinja b/template/{% if tasks == 'tox' %}tox.toml{% endif %}.jinja
@@ -92,12 +92,13 @@ commands = [
     ] },
   ],
 ]
-{%- if docs == 'mkdocs' %}
+{%- if docs %}
 
 [env.docs]
 description = "build the documentation"
 package = "editable"
 dependency_groups = [ "docs" ]
+{%- if docs == 'mkdocs' %}
 commands = [
   [
     "mkdocs",
@@ -109,11 +110,23 @@ commands = [
     { replace = "posargs", extend = true },
   ],
 ]
+{%- elif docs == 'zensical' %}
+commands = [
+  [
+    "zensical",
+    "build",
+    "--clean",
+    "--strict",
+    { replace = "posargs", extend = true },
+  ],
+]
+{%- endif %}
 
 [env.autodocs]
 description = "serve the documentation locally"
 package = "editable"
 dependency_groups = [ "docs" ]
+{%- if docs == 'mkdocs' %}
 commands = [
   [
     "mkdocs",
@@ -122,4 +135,14 @@ commands = [
     { replace = "posargs", extend = true },
   ],
 ]
+{%- elif docs == 'zensical' %}
+commands = [
+  [
+    "zensical",
+    "serve",
+    "--open",
+    { replace = "posargs", extend = true },
+  ],
+]
+{%- endif %}
 {%- endif %}

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +title: API
 +---
++
 +# ::: {{ package_name }}