Merge pull request #50 from stealthrocket/mkdocs

API reference docs

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - mkdocs
+    tags:
+      - '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          cache: pip
+          python-version: '3.11'
+      - run: make docs-deps
+
+      - name: Configure the git user
+        run: |
+          git config user.name "Stealth Rocket"
+          git config user.email "[email protected]"
+
+      - name: Build main branch
+        if: ${{ github.ref_name == 'main' }}
+        run: |
+          mike deploy --push main
+      - name: Build tagged version
+        if: ${{ github.ref_name != 'main' }}
+        run: |
+          mike deploy --push --update-aliases ${{ github.ref_name }} latest

CONTRIBUTING.md

@@ -26,6 +26,16 @@ click around. You can refresh your browser after each `make coverage` run.
 
 Formatting is done with `black`. Run `make fmt`.
 
-Docstrings follow the [Google style][docstrings].
+Docstrings follow the [Google style][docstrings]. All public entities should
+have a docstring attached.
 
 [docstrings]: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings
+
+## Documentation
+
+API reference documentation is automatically built on merges to `main` and new
+tagged version. To view the generated documentation locally:
+
+```
+make local-docs
+```

Makefile

@@ -65,3 +65,10 @@ push:
 
 push-test:
 	twine upload -r testpypi dist/*
+
+
+docs-deps: dev
+	$(PYTHON) -m pip install .[docs]
+
+local-docs: docs-deps
+	mkdocs serve

docs/index.md

@@ -0,0 +1,23 @@
+---
+hide:
+  - navigation
+---
+
+# Dispatch Python SDK
+
+This is the API reference for the Python SDK of Dispatch.
+
+- Tutorials and guides: [docs.stealthrocket.tech][docs].
+- Source: [stealthrocket/dispatch-sdk][github].
+
+
+[docs]: https://docs.stealthrocket.tech
+[github]: https://github.com/stealthrocket/dispatch-sdk
+
+## API Reference
+
+---
+
+::: dispatch
+	options:
+	  show_submodules: true

mkdocs.yml

@@ -0,0 +1,28 @@
+site_name: Dispatch SDK
+
+theme:
+  name: "material"
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch mode based on system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+  - search
+  - mkdocstrings
+  - mike
+
+extra:
+  version:
+    provider: mike

pyproject.toml

@@ -28,6 +28,13 @@ dev = [
     "types-requests >= 2.31.0.20240125"
 ]
 
+docs = [
+     "mkdocs==1.5.3",
+     "mkdocstrings[python]==0.24.0",
+     "mkdocs-material==9.5.9",
+     "mike==2.0.0"
+]
+
 [tool.setuptools-git-versioning]
 enabled = true
 dev_template = "{tag}"