Documentation

.github/workflows/publish-document.yml

@@ -0,0 +1,37 @@
+name: Publish document
+on:
+  push:
+    branches:
+      - master
+      - 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 mkdocs-material
+          pip install 'mkdocstrings[python]'
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.gitignore

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

CONTRIBUTING.md

@@ -156,6 +156,31 @@ To format and lint the codes,
 tox -e fmt,lint
 ```
 
+## [Optional] Documentation setup
+
+This repository uses [mkdocs](https://github.com/mkdocs/mkdocs/tree/master) to generate a documentation from python docstring. As long as you write docstrings for your code, the document (API references section) will be automatically updated when the code is merged into `main` branch, so there is no need for you to do anything.
+
+If you want to manually edit the document, please run the following commands to setup the editing environment.
+
+```bash
+pip install mkdocs-material
+pip install 'mkdocstrings[python]'
+```
+
+You can edit the documentation at `docs` folder (i.e. `docs/index.md`) to update the document.
+
+In order to view the current documentation locally, run the following command. This will host the document at your local server.
+
+```bash
+mkdocs serve
+```
+
+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