Merge pull request #8 from matagus/docs-using-mkdocs-rtd-and-gh-pages

Docs using MkDocs + Material theme, published to RTD and gh pages

README.md

@@ -32,17 +32,17 @@ pipelines for:
 config.
 - [x] Sync updates from newest versions of this template with [Copier](https://copier.readthedocs.io/en/stable/updating/).
 - [x] Standardised list of GitHub labels synchronised on push to main branch using [the labels CLI](https://github.com/hackebrot/labels).
+- [x] Documentation with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and docstring reference
+support with [mkdocstrings](https://mkdocstrings.github.io/).
+- [x] Latest stable documentation published to [GitHub](https://docs.github.com/en/pages)/[GitLab](https://docs.gitlab.com/ee/user/project/pages/) Pages.
 
 
 ## Coming Soon
 
-- [ ] Documentation with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and docstring reference
-support with [mkdocstrings](https://mkdocstrings.github.io/).
-- [ ] Latest stable documentation published to [GitHub](https://docs.github.com/en/pages)/[GitLab](https://docs.gitlab.com/ee/user/project/pages/) Pages.
 - [ ] [Versioned documentation](https://docs.readthedocs.io/en/stable/versions.html) and [pull request previews](https://docs.readthedocs.io/en/stable/pull-requests.html) with [Read the Docs](https://readthedocs.org/).
 - [ ] Containerization for development and deployment with [dev container](https://containers.dev/).
 - [ ] Follow the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
-- [  ] Turn Github repository in to a [Template Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
+- [ ] Turn Github repository in to a [Template Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
 that does all the setup so people don't need to install copier and run it locally. Similar to what Simon Willison did
 with [his cookicutter template](https://github.com/simonw/python-lib-template-repository)
 

src/.github/workflows/gh-pages.yml

@@ -0,0 +1,20 @@
+name: Publish docs via GitHub Pages
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: requirements.txt

src/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+     - method: pip
+       path: .
+       extra_requirements:
+         - docs

src/docs/index.md.jinja

@@ -0,0 +1,11 @@
+# Getting started with {{ project_name }}
+
+{{ project_description }}
+
+## Installation
+
+Install using pip:
+
+```bash
+pip install {{ module_name }}
+```

src/pyproject.toml.jinja

@@ -57,11 +57,27 @@ include = [
     "{{ module_name }}/",
 ]
 
+[project.optional-dependencies]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "pygments",
+    "pymdown-extensions",
+]
+
 [tool.hatch.envs.default]
 dependencies = [
     "Django>=4.0", "ipython", "ipdb", "mypy", "typing-extensions", "django-extensions", "Werkzeug"
 ]
 
+[tool.hatch.envs.docs]
+dependencies = ["mkdocs", "mkdocs-material", "pygments", "pymdown-extensions"]
+
+[tool.hatch.envs.docs.scripts]
+new = "mkdocs new ."
+build = "mkdocs build {args}"
+serve = "mkdocs serve {args}"
+
 [tool.hatch.envs.project]
 dependencies = [
     "Django>=4.0", "ipython", "ipdb", "mypy", "typing-extensions", "django-extensions", "Werkzeug"