87 add support for using zensical

.github/actions/setup-python-env/action.yml

@@ -9,7 +9,7 @@ inputs:
   uv-version:
     description: "uv version to use"
     required: true
-    default: "0.10.10"
+    default: "0.10.12"
 
 runs:
   using: "composite"

.github/workflows/main.yml

@@ -68,4 +68,4 @@ jobs:
         uses: ./.github/actions/setup-python-env
 
       - name: Check if documentation can be built
-        run: uv run mkdocs build -s
+        run: uv run zensical build -s

.github/workflows/on-release-main.yml

@@ -1,11 +1,23 @@
 name: release-main
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 on:
   release:
     types: [published]
 
 jobs:
   deploy-docs:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
       - name: Check out
@@ -14,5 +26,14 @@ jobs:
       - name: Set up the environment
         uses: ./.github/actions/setup-python-env
 
-      - name: Deploy documentation
-        run: uv run mkdocs gh-deploy --force
+      - name: Build documentation
+        run: uv run zensical build --clean
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -115,7 +115,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# zensical documentation
 /site
 
 # mypy

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
         exclude: ^{{cookiecutter.project_name}}/
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.6"
+    rev: "v0.15.7"
     hooks:
       - id: ruff-check
         args: [--exit-non-zero-on-fix, --config=pyproject.toml]

Makefile

@@ -75,11 +75,11 @@ build-and-publish: build publish ## Build and publish.
 
 .PHONY: docs-test
 docs-test: ## Test if documentation can be built without warnings or errors
-	@uv run mkdocs build -s
+	@uv run zensical build -s
 
 .PHONY: docs
 docs: ## Build and serve the documentation
-	@uv run mkdocs serve
+	@uv run zensical serve
 
 .PHONY: help
 help:

README.md

@@ -18,7 +18,7 @@ This is a modern Cookiecutter template that can be used to initiate a Python pro
 - Code quality with [ruff](https://github.com/charliermarsh/ruff), [mypy](https://mypy.readthedocs.io/en/stable/)/[ty](https://docs.astral.sh/ty/) and [deptry](https://github.com/fpgmaas/deptry/).
 - Publishing to [PyPI](https://pypi.org) by creating a new release on GitHub
 - Testing and coverage with [pytest](https://docs.pytest.org/en/7.1.x/) and [codecov](https://about.codecov.io/)
-- Documentation with [MkDocs](https://www.mkdocs.org/)
+- Documentation with [MkDocs](https://www.mkdocs.org/) or [Zensical](https://zensical.org)
 - Compatibility testing for multiple versions of Python with [tox-uv](https://github.com/tox-dev/tox-uv)
 - Containerization with [Docker](https://www.docker.com/) or [Podman](https://podman.io/)
 - Development environment with [VSCode devcontainers](https://code.visualstudio.com/docs/devcontainers/containers)

cookiecutter.json

@@ -21,9 +21,10 @@
     "y",
     "n"
   ],
-  "mkdocs": [
-    "y",
-    "n"
+  "docs_tool": [
+    "mkdocs",
+    "zensical",
+    "none"
   ],
   "codecov": [
     "y",

docs/features/cicd.md

@@ -26,8 +26,8 @@ formatting.
 made on the `main` branch. In addition, `on-release-main.yml` also
 publishes the project to PyPI if `publish_to_pypi` is set to
 `"y"`, and it builds and deploys the documentation
-if `mkdocs` is set to `"y"`. To learn more about these features,
-see [Publishing to PyPI](./publishing.md) and [Documentation with MkDocs](./mkdocs.md)
+if `docs_tool` is set to `"mkdocs"` or `"zensical"`. To learn more about these features,
+see [Publishing to PyPI](./publishing.md) and [Documentation with MkDocs/Zensical](./docs_tool.md)
 
 Additionally, all workflows check for compatibility with multiple Python
 versions if `tox` is set to `"y"`.

docs/features/mkdocs.md → docs/features/docs_tool.md

@@ -1,10 +1,10 @@
-# Documentation with MkDocs
+# Documentation with MkDocs or Zensical
 
-If `mkdocs` is set to `"y"`, documentation of your project is
+If `docs_tool` is set to `"mkdocs"` or `"zensical"`, documentation of your project is
 automatically added using
-[MkDocs](https://www.mkdocs.org/). Next to that, if
+[MkDocs](https://www.mkdocs.org/) or [Zensical](https://zensical.org). Next to that, if
 `"include_github_actions"` is set to `"y"`, the documentation is
-automatically deployed to your `gh-pages` branch, and made available at
+automatically deployed github action artifacts, and made available at
 `https://<github_handle>.github.io/<project_name>/`.
 
 To view the documentation locally, simply run
@@ -16,16 +16,24 @@ make docs
 This command will generate and build your documentation, and start the server locally so you can access it at
 <http://localhost:8000>.
 
-## Enabling the documentation on GitHub
+## Deploying to GitHub Pages
 
-To enable your documentation on GitHub, first navigate to `Settings > Actions > General` in your repository, and under `Workflow permissions` select `Read and write permissions`
+Documentation is automatically built and deployed whenever you create a
+[new release](./cicd.md#how-to-trigger-a-release) for your project.
 
-Then, create a [new release](./cicd.md#how-to-trigger-a-release) for your project.
+### Initial Setup (One-time only)
 
-Then, in your repository, navigate to `Settings > Code and Automation > Pages`. If you succesfully created a new release,
-you should see a notification saying ` Your site is ready to be published at https://<author_github_handle>.github.io/<project_name>/`.
+To enable the modern deployment pipeline, you must configure your repository to
+use GitHub Actions for hosting:
 
-To finalize deploying your documentation, under `Source`, select the branch `gh-pages`. Your documentation should then be live within a few minutes.
+1. Navigate to Settings > Code and automation > Pages in your GitHub repository.
+2. Under Build and deployment > Source, change the dropdown selection from "Deploy
+from a branch" to GitHub Actions.
+
+### Viewing your site
+
+Once a release workflow has finished, your site will be live at:
+https://<author_github_handle>.github.io/<project_name>/
 
 ## Documenting docstrings
 

docs/features/index.md

@@ -0,0 +1,5 @@
+---
+icon: material/star
+---
+
+#

docs/index.md

@@ -1,3 +1,7 @@
+---
+icon: material/home-circle
+---
+
 <p align="center">
   <img width="600" src="static/cookiecutter.svg">
 </p style = "margin-bottom: 2rem;">
@@ -19,7 +23,7 @@ This is a modern Cookiecutter template that can be used to initiate a Python pro
 - Code quality with [ruff](https://github.com/charliermarsh/ruff), [mypy](https://mypy.readthedocs.io/en/stable/)/[ty](https://docs.astral.sh/ty/) and [deptry](https://github.com/fpgmaas/deptry/).
 - Publishing to [PyPI](https://pypi.org) by creating a new release on GitHub
 - Testing and coverage with [pytest](https://docs.pytest.org/en/7.1.x/) and [codecov](https://about.codecov.io/)
-- Documentation with [MkDocs](https://www.mkdocs.org/)
+- Documentation with [MkDocs](https://www.mkdocs.org/) or [Zensical](https://zensical.org)
 - Compatibility testing for multiple versions of Python with [tox-uv](https://github.com/tox-dev/tox-uv)
 - Containerization with [Docker](https://www.docker.com/) or [Podman](https://podman.io/)
 - Development environment with [VSCode devcontainers](https://code.visualstudio.com/docs/devcontainers/containers)

docs/prompt_arguments.md

@@ -1,3 +1,7 @@
+---
+icon: material/console-line
+---
+
 # Prompt arguments
 
 When running the command `ccp` a prompt will start which enables you to configure your repository. The
@@ -61,12 +65,12 @@ see
 `"y"` or `"n"`. Adds [deptry](https://fpgmaas.github.io/deptry/)
 to the development dependencies of the project, and adds it to the `make check` command. `deptry` is a command line tool to check for issues with dependencies in a Python project, such as obsolete or missing dependencies.
 
-**mkdocs**
+**docs_tool**
 
-`"y"` or `"n"`. Adds [MkDocs](https://www.mkdocs.org/)
-documentation to your project. This includes automatically parsing
-your docstrings and adding them to the documentation. Documentation
-will be deployed to the `gh-pages` branch.
+`"mkdocs"`, `"zensical"` or `"none"`. Adds [MkDocs](https://www.mkdocs.org/) or
+[Zensical](https://zensical.org) documentation to your project. This includes automatically parsing
+your docstrings and adding them to the documentation. Documentation is automatically deployed to
+GitHub Pages via the release-main workflow upon every new release.
 
 **codecov**
 

docs/stylesheets/extra.css

@@ -24,18 +24,21 @@
 }
 
 [data-md-color-scheme="astral-light"] {
-  --md-default-bg-color--dark: var(--black);
-  --md-primary-fg-color: var(--galaxy);
-  --md-typeset-a-color: var(--flare);
-  --md-accent-fg-color: var(--cosmic);
+  --md-default-bg-color: var(--white);
+  --md-default-bg-color--light: var(--comet);
+  --md-default-fg-color: var(--black);
+  --md-default-fg-color--light: var(--black);
+  --md-default-fg-color--lighter: var(--black);
+  --md-primary-bg-color: var(--white);
+  --md-accent-fg-color: var(--galaxy);
 }
 
 [data-md-color-scheme="astral-dark"] {
   --md-default-bg-color: var(--black);
+  --md-default-bg-color--light: var(--space);
   --md-default-fg-color: var(--white);
   --md-default-fg-color--light: var(--white);
   --md-default-fg-color--lighter: var(--white);
-  --md-primary-fg-color: var(--space);
   --md-primary-bg-color: var(--white);
   --md-accent-fg-color: var(--cosmic);
 
@@ -65,3 +68,16 @@
   --md-typeset-table-color: hsla(0, 0%, 100%, 0.12);
   --md-typeset-table-color--light: hsla(0, 0%, 100%, 0.035);
 }
+
+.md-nav__link {
+  display: flex;
+  align-items: center;
+  font-size: 0.65rem;
+  padding-top: 0.2rem;
+  padding-bottom: 0.2rem;
+}
+
+.md-nav__link .md-nav__icon.md-icon {
+  height: 0.7rem;
+  width: 0.7rem;
+}

docs/tutorial.md

@@ -1,3 +1,7 @@
+---
+icon: material/rocket-launch
+---
+
 # Tutorial
 
 This page contains a complete tutorial on how to create your project.

hooks/post_gen_project.py

@@ -27,12 +27,17 @@ def move_dir(src: str, target: str) -> None:
     if "{{cookiecutter.include_github_actions}}" != "y":
         remove_dir(".github")
     else:
-        if "{{cookiecutter.mkdocs}}" != "y" and "{{cookiecutter.publish_to_pypi}}" == "n":
+        if "{{cookiecutter.docs_tool}}" not in ["mkdocs", "zensical"] and "{{cookiecutter.publish_to_pypi}}" == "n":
             remove_file(".github/workflows/on-release-main.yml")
 
-    if "{{cookiecutter.mkdocs}}" != "y":
+    if "{{cookiecutter.docs_tool}}" == "mkdocs":
+        remove_file("zensical.toml")
+    elif "{{cookiecutter.docs_tool}}" == "zensical":
+        remove_file("mkdocs.yml")
+    else:  # none
         remove_dir("docs")
         remove_file("mkdocs.yml")
+        remove_file("zensical.toml")
 
     if "{{cookiecutter.dockerfile}}" != "y":
         remove_file("Dockerfile")