Documentation

.github/workflows/publish-document.yml

@@ -0,0 +1,34 @@
+name: Publish document
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout Repository
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        name: Setup Python
+        with:
+          python-version: 3.12
+      - name: Set Cache ID
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        name: Restore/Save Cache
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install mkdocs dependencies
+        run: pip install tox
+      - name: Deploy documentation to GitHub Pages
+        run: tox -e docs -- gh-deploy --force

.gitignore

@@ -26,3 +26,6 @@ venv/
 
 # Setuptools scm version
 _version.py
+
+# mkdocs documentation
+/site

CONTRIBUTING.md

@@ -156,6 +156,33 @@ To format and lint the codes,
 tox -e fmt,lint
 ```
 
+This repository uses [mkdocs](https://github.com/mkdocs/mkdocs/tree/master) to generate a documentation from python docstring. As long as you write the docstrings for your code, the document (API references section) will be updated whenever you run `tox -e docs` command. The document will be automatically published when your PR is merged into `main` branch.
+
+To build the documentation based on your current codes, run the following command. This will outputs the documentation into `./site` folder.
+
+```bash
+tox -e docs
+```
+
+To run other mkdocs command,
+
+```bash
+tox -e docs -- <mkdocs command>
+
+# For instance, serve the current documentation locally,
+tox -e docs -- serve
+...
+INFO    -  [17:35:25] Serving on http://127.0.0.1:8000/
+```
+
+You can also manually edit or add pages to the documentation by modifying files under `./docs` folder.
+
+For more information about mkdocs, please refer to their documentations:
+
+- mkdocs: https://github.com/mkdocs/mkdocs/tree/master
+- mkdocs material (material theme wrapper for mkdocs): https://github.com/squidfunk/mkdocs-material
+- mkdocstrings (plugin to automatically generate documentation from docstrings): https://github.com/mkdocstrings/mkdocstrings
+
 # Your First Contribution
 
 Would you like to help drive the community forward? We will help you understand the organization of the project and direct you to the best places to get started. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged.

docs/API References.md

@@ -0,0 +1,3 @@
+<!-- Auto generate API references with mkdocstrings https://mkdocstrings.github.io/usage/#usage -->
+
+::: oper8

docs/index.md

@@ -0,0 +1,5 @@
+# Oper8
+
+Oper8 is a framework for writing kubernetes operators in python. It implements many common patterns used by large cloud applications that are reusable across many operator design patterns ([GitHub](https://github.com/IBM/oper8/tree/main)).
+
+For API details, please refer to the [API References](API References.md).

mkdocs.yml

@@ -0,0 +1,31 @@
+site_name: "oper8"
+nav:
+  - Home: index.md
+  - API References: API References.md
+theme:
+  name: material
+  font:
+    text: IBM Plex Sans
+    code: IBM Plex Mono
+  palette:
+    # Dark Mode
+    - scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Dark mode
+      primary: black
+      accent: deep purple
+    # Light Mode
+    - scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Light mode
+      primary: white
+      accent: indigo
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_submodules: true

pyproject.toml

@@ -62,9 +62,8 @@ dev-test = [
 ]
 
 dev-docs = [
-    "sphinx>=4.0.2,<9.0",
-    "sphinx-autoapi>=2.1.0",
-    "sphinx-rtd-theme>=1.2.1,<3.1.0",
+    "mkdocs-material>=9.5.46",
+    "mkdocstrings-python>=1.12.2"
 ]
 
 dev-fmt = [

scripts/document.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+set -e
+BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$BASE_DIR"
+
+mkdocs_opt=("$@")
+
+if [[ ${#mkdocs_opt[@]} -eq 0 ]]; then
+    echo "No options provided. Running 'mkdocs build'..."
+    mkdocs build
+    exit 0
+fi
+
+# Modify set e because serve will be aborted with ctrl C.
+if [[ "${mkdocs_opt[0]}" == "serve" ]]; then
+    set +e
+    echo "Serving the documentation. Abort with ctrl C."
+fi
+
+echo "Running 'mkdocs ${mkdocs_opt[@]}'..."
+mkdocs "${mkdocs_opt[@]}"

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py, lint, fmt
+envlist = py, lint, fmt, docs
 
 [testenv]
 description = run tests with pytest with coverage
@@ -20,16 +20,11 @@ allowlist_externals = ./scripts/run_tests.sh
 ; Without this, sdist packaging is tested so that's a start.
 package=wheel
 
-; TODO -- Enable docs!!
-; [testenv:docs]
-; recreate = True
-; extras = dev-docs
-; changedir = docs/source
-
-; ; Disabled '-W' flag as warnings in the files
-; ; TOTO: Add back in once build warnings fixed
-; commands =
-;   sphinx-build -E -a -b html -T . _build/html
+[testenv:docs]
+description = build documentation
+extras = dev-docs
+commands = ./scripts/document.sh {posargs}
+allowlist_externals = ./scripts/document.sh
 
 [testenv:fmt]
 description = format with pre-commit