docs: add skeleton for publishing docs to github.io

.github/workflows/publish-docs.yml

@@ -0,0 +1,39 @@
+name: Publish docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:  # Allows to trigger the workflow manually in GitHub UI
+
+jobs:
+  run:
+    name: "deploy docs"
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        # See <https://github.com/mkdocs/mkdocs/issues/2370#issuecomment-821926264>
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.12
+
+    - name: Set up pip cache
+      if: runner.os == 'Linux'
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+        restore-keys: ${{ runner.os }}-pip-
+
+    - name: Install hatch
+      run: |
+        pipx install hatch
+
+    - name: Publish doc
+      run: hatch env run -e docs mkdocs gh-deploy

Makefile

@@ -14,6 +14,9 @@ test:
 wheel:
 	hatch build
 
+doc:  # use 'doc' instead of 'docs', as 'make docs' is a make command
+	hatch env run -e docs mkdocs build
+
 clean:
 	hatch clean
 
@@ -23,8 +26,9 @@ clean:
 
 help:
 	@echo '----'
-	@echo 'format                       - run code formatters'
 	@echo 'lint                         - run linters'
+	@echo 'format                       - run code formatters'
 	@echo 'test                         - run unit tests'
 	@echo 'wheel                        - build wheel package'
+	@echo 'doc                          - build documentation site'
 	@echo 'clean                        - clean up'

docs/index.md

@@ -0,0 +1,36 @@
+# Home
+
+This site contains the project documentation for the
+`calculator` project that is a toy module used in the
+Real Python tutorial
+[Build Your Python Project Documentation With MkDocs](
+    https://realpython.com/python-project-documentation-with-mkdocs/).
+Its aim is to give you a framework to build your
+project documentation using Python, MkDocs,
+mkdocstrings, and the Material for MkDocs theme.
+
+## Table Of Contents
+
+The documentation follows the best practice for
+project documentation as described by Daniele Procida
+in the [Diátaxis documentation framework](https://diataxis.fr/)
+and consists of four separate parts:
+
+1. [Tutorials](tutorials.md)
+2. [How-To Guides](how-to-guides.md)
+3. [Reference](reference.md)
+4. [Explanation](explanation.md)
+
+Quickly find what you're looking for depending on
+your use case by looking at the different pages.
+
+## Project Overview
+
+::: tablegpt
+
+## Acknowledgements
+
+I want to thank my house plants for providing me with
+a negligible amount of oxygen each day. Also, I want
+to thank the sun for providing more than half of their
+nourishment free of charge.

docs/reference.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: tablegpt.agent.create_tablegpt_graph

mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: TableGPT Agent
+
+theme:
+  name: "material"
+
+plugins:
+  - mkdocstrings
+
+nav:
+  - index.md
+  - tutorials.md
+  - how-to-guides.md
+  - reference.md
+  - explanation.md

pyproject.toml

@@ -50,6 +50,13 @@ extra-dependencies = [
 [tool.hatch.envs.types.scripts]
 check = "mypy --install-types --non-interactive {args:src/tablegpt tests}"
 
+[tool.hatch.envs.docs]
+dependencies = [
+  "mkdocs",
+  "mkdocstrings[python]",
+  "mkdocs-material",
+]
+
 [tool.coverage.run]
 source_pkgs = ["tablegpt", "tests"]
 branch = true