diff --git a/.github/workflows/publish-document.yml b/.github/workflows/publish-document.yml new file mode 100644 index 0000000..590def7 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index a27d5f4..2bcb357 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,6 @@ venv/ # Setuptools scm version _version.py + +# mkdocs documentation +/site diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c8ed7b..d50bb27 100644 --- a/CONTRIBUTING.md +++ b/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 -- + +# 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. diff --git a/docs/API References.md b/docs/API References.md new file mode 100644 index 0000000..7a3a45c --- /dev/null +++ b/docs/API References.md @@ -0,0 +1,3 @@ + + +::: oper8 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ef5c0ed --- /dev/null +++ b/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). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f0e7145 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index b828c32..0a90a36 100644 --- a/pyproject.toml +++ b/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 = [ diff --git a/scripts/document.sh b/scripts/document.sh new file mode 100755 index 0000000..d7ecd61 --- /dev/null +++ b/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[@]}" diff --git a/tox.ini b/tox.ini index 637013e..6ab23ec 100644 --- a/tox.ini +++ b/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