🔧 Template: Add Read the Docs deployment for MkDocs

Basic configuration from the RTD documentation:

https://docs.readthedocs.com/platform/stable/intro/mkdocs.html

We just fix the Python version to 3.13 for more deterministic builds.
We add the option to the corresponding `copier` question, but only in case MkDocs is
selected for the documentation engine.

Author: mbercx

README.md

@@ -10,7 +10,7 @@ Template for Python packages based on [`copier`](https://copier.readthedocs.io/e
 * 📚 **Documentation**: Document your package in [MyST](https://mystmd.org/) or [MkDocs](https://www.mkdocs.org/).
 * 🧹 **Pre-commit**: Format and lint your code with [Ruff](https://docs.astral.sh/ruff/).
 * ⚙️ **GitHub Actions**:
-    * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site).
+    * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) or [Read the Docs](https://about.readthedocs.com/).
     * Run pre-commit checks and tests on every pull request.
 
 ## Usage

copier.yml

@@ -19,9 +19,12 @@ docs:
 doc_deploy:
   type: str
   help: 'Where do you want to deploy your documentation?'
-  choices:
+  choices: |
     - nowhere
     - github
+    {%- if docs == 'mkdocs' %}
+    - rtd
+    {%- endif %}
   default: nowhere
 
 _subdirectory: template

docs/index.md

@@ -5,10 +5,10 @@ A `copier`-based template for Python packages.
 ## Features
 
 * 📦 **Package management**: Test, build, and deploy your package with [Hatch](https://hatch.pypa.io/) environments.
-* 📚 **Documentation**: Document your package with [MyST](https://mystmd.org/) or [MkDocs](https://www.mkdocs.org/).
+* 📚 **Documentation**: Document your package in [MyST](https://mystmd.org/) or [MkDocs](https://www.mkdocs.org/).
 * 🧹 **Pre-commit**: Format and lint your code with [Ruff](https://docs.astral.sh/ruff/).
 * ⚙️ **GitHub Actions**:
-    * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site).
+    * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) or [Read the Docs](https://about.readthedocs.com/).
     * Run pre-commit checks and tests on every pull request.
 
 ## Usage
@@ -21,3 +21,16 @@ copier copy https://github.com/mbercx/python-copier <package_name>
 ```
 
 And answer the questions to generate a new Python package.
+
+## Next steps
+
+After copying the template, you might still have to do some additional configuration.
+
+### Deploy documentation
+
+#### Read the Docs
+
+1. Push your code to GitHub.
+2. Go to [Read the Docs](https://readthedocs.org/) (RTD) and [import your project](https://docs.readthedocs.com/platform/stable/tutorial/index.html#importing-the-project-to-read-the-docs).
+   The build will use the included `.readthedocs.yaml` automatically.
+3. Set the RTD settings to [build from GitHub pull requests](https://docs.readthedocs.com/platform/stable/tutorial/index.html#triggering-builds-from-pull-requests).

template/{% if doc_deploy == 'rtd' %}.readthedocs.yml{% endif %}.jinja

@@ -0,0 +1,12 @@
+ version: 2
+
+ build:
+   os: "ubuntu-24.04"
+   tools:
+     python: "3.13"
+   jobs:
+     pre_install:
+       - pip install mkdocs-material
+
+ mkdocs:
+   configuration: mkdocs.yml