✨ Allow user to choose documentation tool

Currently the package template only offers MyST for the documentation generator tool.
However, some users might prefer to use MkDocs for its simplicity and sleek look.
Here we adapt the template to give users the option to select their preffered
documentation tool.

On the template package level, we remove the `default.docs` command, which copied the
template and then served its documenation with `myst start`. Providing options for both
MyST and MkDocs options will clutter the default environment with too many scripts,
and serving the package documentation is also done easily after doing `hatch run copy`.

Author: mbercx

copier.yml

@@ -2,11 +2,20 @@ package_name:
   type: str
   help: 'What is the name of your Python package?'
   default: '{{_folder_name }}'
+
 description:
   type: str
   help: 'Describe what your Python package is for.'
   default: 'Python package'
 
+docs:
+  type: str
+  help: 'Which documentation engine do you prefer?'
+  choices:
+    - myst
+    - mkdocs
+  default: myst
+
 _subdirectory: template
 _message_after_copy: |
   The `{{package_name}}` package has been created successfully!

docs/design.md

@@ -35,11 +35,24 @@ This pattern has a few advantages:
 
 ## Documentation
 
-We use [MyST Markdown](https://mystmd.org/) for our Python package documentation.
-We want to use a Markdown-based documentation tool for simplicity, avoiding Sphinx' reStructuredText format.
+The user can select which documentation engine they prefer.
+Some information on the two options is already provided below, this will be fleshed out more as both frameworks are tested more rigorously.
+
+## MyST Markdown
+
+[MyST Markdown](https://mystmd.org/) is a Markdown-based documentation tool that avoids Sphinx' reStructuredText format while preserving most of its power.
 The main reason to use this over [MkDocs](https://www.mkdocs.org/) to test the Jupyter notebook integration, especially the "executable content".
 MyST is also easy to integrate with Sphinx, which has a lot of powerful tools, especially for scientific software.
 
+## MkDocs
+
+[MkDocs](https://www.mkdocs.org/) is another Markdown-based documentation tool that focusses even more on simplicity.
+Some features:
+
+1. Very simple to build and write, not too much faff.
+1. Static pages, easy to host.
+1. Sleek look, using [Material for MkDocs](https://github.com/squidfunk/mkdocs-material).
+
 ## DevOps
 
 This template includes development automation tools that ensure code quality, consistency, and developer efficiency.

docs/developer.md

@@ -26,7 +26,6 @@ Other scripts for the default environment:
 
 * `check`: Copy/Update the template in the `.tmp` directory and check the rendered files by linting them with `hatch fmt -l`.
 * `clean`: Remove the `.tmp` directory and any Ruff caches.
-* `docs`: Copy/Update the template in the `.tmp` directory and serve the documentation with `myst start`.
 * `install`: Copy/Update the template in the `.tmp` directory and install it with `uv pip install`.
 
 ## Documentation

pyproject.toml

@@ -15,16 +15,11 @@ scripts.check = [
   "copier copy --vcs-ref=HEAD . .tmp/py-package -f",
   "hatch fmt -l --check .tmp/py-package",
 ]
-scripts.docs = [
-  "copier copy --vcs-ref=HEAD . .tmp/py-package -f",
-  "cd .tmp/py-package/docs && myst start",
-]
 scripts.clean = [
   "ruff clean",
   "rm -rf .tmp",
 ]
 
-
 [tool.hatch.envs.docs]
 detached = true
 dependencies = [

template/docs/myst.yml.jinja …cs == 'myst' %}myst.yml{% endif %}.jinjatemplate/docs/myst.yml.jinja renamed to template/docs/{% if docs == 'myst' %}myst.yml{% endif %}.jinja template/docs/myst.yml.jinja renamed to template/docs/{% if docs == 'myst' %}myst.yml{% endif %}.jinja

@@ -24,14 +24,24 @@ classifiers = [
 [tool.hatch.version]
 path = "src/{{ package_name.lower().replace('-', '_') }}/__about__.py"
 
-
+{% if docs == 'myst'-%}
 [tool.hatch.envs.docs]
 dependencies = [
   "mystmd"
 ]
 scripts.build = "cd docs && myst build"
 scripts.start = "cd docs && myst start"
+{%- endif -%}
 
+{%- if docs == 'mkdocs' -%}
+[tool.hatch.envs.docs]
+dependencies = [
+  "mkdocs",
+  "mkdocs-material"
+]
+scripts.build = "mkdocs build --clean --strict"
+scripts.serve = "mkdocs serve --dev-addr localhost:8000"
+{%- endif %}
 
 [tool.hatch.envs.precommit]
 dependencies = ["pre-commit"]

template/pyproject.toml.jinja

@@ -0,0 +1,3 @@
+site_name: {{package_name}}
+theme:
+  name: material