docs: improve documentation setup

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  release:
+    types: [created]
+
+# https://docs.github.com/en/actions/using-jobs/using-concurrency
+concurrency:
+  group: docs-${{ github.head_ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    # do not run in forks
+    if: github.repository == 'afuetterer/services-test4'
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1 # v4.7.0
+        with:
+          python-version: "3.11"
+
+      - uses: actions/cache@v3
+        with:
+          key: docs-${{ hashFiles('pyproject.toml') }}
+          path: ~/.cache/pip
+
+      - name: Ensure latest pip
+        run: python -m pip install --upgrade pip setuptools wheel
+
+      - name: Install hatch
+        run: pip install --upgrade hatch
+
+      - name: Build documentation
+        run: hatch run docs:build
+
+      - name: Deploy documentation
+        run: hatch run docs:deploy

.pre-commit-config.yaml

@@ -1,4 +1,7 @@
+# pre-commit
 # https://pre-commit.com/#usage
+# ------------------------------------------------------------------------------
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: f71fa2c1f9cf5cb705f73dffe4b21f7c61470ba9 # frozen: v4.4.0

docs/changelog.md

@@ -0,0 +1 @@
+{% include-markdown "../CHANGELOG.md" %}

docs/gen_ref_pages.py

@@ -0,0 +1,38 @@
+"""Generate the code reference pages and navigation.
+
+The code below is taken from the mkdocstrings recipes (licensed under ISC License):
+https://mkdocstrings.github.io/recipes/
+https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/gen_ref_nav.py
+"""
+
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("src").rglob("*.py")):
+    module_path = path.relative_to("src").with_suffix("")
+    doc_path = path.relative_to("src", "services_test4").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, Path("../") / path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.txt", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/index.md

@@ -0,0 +1 @@
+{% include-markdown "../README.md" %}

docs/license.md

@@ -0,0 +1 @@
+{% include-markdown "../LICENSE.md" %}

mkdocs.yml

@@ -1,13 +1,17 @@
-site_name: services-test2
-site_description: services-test2
-repo_name: afuetterer/services-test2
-repo_url: https://github.com/afuetterer/services-test2
-watch: [README.md, src/services_test2]
+# mkdocs
+# https://www.mkdocs.org/user-guide/configuration/
+# ------------------------------------------------------------------------------
+
+site_name: services-test4
+site_description: services-test4
+repo_name: afuetterer/services-test4
+repo_url: https://github.com/afuetterer/services-test4
+watch: [README.md, src/services_test4]
 
 nav:
   - Home: index.md
-  - Usage: cli.md
-  - Reference: reference/
+  # - Usage: cli.md
+  # - Reference: reference/
   - Changelog: changelog.md
   - License: license.md
 
@@ -18,11 +22,11 @@ theme:
 
 plugins:
   - search
-  - mkdocstrings:
-      handlers:
-        python:
-          options:
-            docstring_style: google
+  # - mkdocstrings:
+  #     handlers:
+  #       python:
+  #         options:
+  #           docstring_style: google
   - include-markdown
   - gen-files:
       scripts:

pyproject.toml

@@ -75,23 +75,31 @@ extra-dependencies = [
   "mypy",
 ]
 [tool.hatch.envs.lint.scripts]
-style = [
-  "pre-commit run --all-files --color=always",
-]
+style = "pre-commit run --all-files --color=always"
 typing = "mypy src tests"
 all = [
   "style",
   "typing",
 ]
 
 [tool.hatch.envs.docs]
-detached = true
+# detached = true
 dependencies = [
-  # TODO: pin?
   "mkdocs>=1.4",
+  "mkdocstrings[python]>=0.20",
+  "mkdocs-click>=0.8",
+  "mkdocs-include-markdown-plugin>=5.1",
+  "mkdocs-gen-files>=0.5",
+  "mkdocs-literate-nav>=0.6",
   "mkdocs-material>=9.1",
+  "mkdocs-section-index>=0.3",
 ]
 
+[tool.hatch.envs.docs.scripts]
+build = "mkdocs build --verbose"
+serve = "mkdocs serve --verbose"
+deploy = "mkdocs gh-deploy --force --verbose"
+
 [tool.hatch.envs.release]
 detached = true
 dependencies = [

templates/CHANGELOG.md.j2

@@ -1,8 +1,6 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Available releases: <https://github.com/afuetterer/services-test4/releases>