From 5dbfc969ce8fd5cd9797f1a86b0a972c2922bdcd Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Fri, 20 Dec 2024 09:52:16 +0900 Subject: [PATCH 1/7] chore: adding documentation workflow. Signed-off-by: Yuki Ito --- .github/workflows/publish-document.yml | 37 ++++++++++++++++++++++++++ .gitignore | 3 +++ docs/API References.md | 3 +++ docs/index.md | 5 ++++ mkdocs.yml | 31 +++++++++++++++++++++ 5 files changed, 79 insertions(+) create mode 100644 .github/workflows/publish-document.yml create mode 100644 docs/API References.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/publish-document.yml b/.github/workflows/publish-document.yml new file mode 100644 index 0000000..23ea2b2 --- /dev/null +++ b/.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 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/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..144536f --- /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 \ No newline at end of file From 27f605b3b367eb4073bad707b3e492a0949ee355 Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Fri, 20 Dec 2024 11:46:20 +0900 Subject: [PATCH 2/7] doc: adding steps for mkdocs setup. Signed-off-by: Yuki Ito --- CONTRIBUTING.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c8ed7b..6cde09b 100644 --- a/CONTRIBUTING.md +++ b/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. From 82e7315ede81d14fa45329ae68790fb076d0f46d Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Fri, 20 Dec 2024 12:28:30 +0900 Subject: [PATCH 3/7] style: formatting mkdocs.yml. Signed-off-by: Yuki Ito --- mkdocs.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 144536f..f0e7145 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,9 +23,9 @@ theme: primary: white accent: indigo plugins: -- search -- mkdocstrings: - handlers: - python: - options: - show_submodules: true \ No newline at end of file + - search + - mkdocstrings: + handlers: + python: + options: + show_submodules: true From 89b0527f80c8fa6b4e821800c1fa2b28d5c38e46 Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Sat, 21 Dec 2024 09:30:09 +0900 Subject: [PATCH 4/7] fix: removing unnecessary branch to trigger publish document workflow. Signed-off-by: Yuki Ito --- .github/workflows/publish-document.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/publish-document.yml b/.github/workflows/publish-document.yml index 23ea2b2..4286478 100644 --- a/.github/workflows/publish-document.yml +++ b/.github/workflows/publish-document.yml @@ -2,7 +2,6 @@ name: Publish document on: push: branches: - - master - main permissions: contents: write From 457dbf4186f09bb5af2be53b88166ecd6491175e Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Sat, 21 Dec 2024 17:26:13 +0900 Subject: [PATCH 5/7] chore: adding tox configuration for mkdocs. Signed-off-by: Yuki Ito --- pyproject.toml | 5 ++--- scripts/document.sh | 22 ++++++++++++++++++++++ tox.ini | 17 ++++++----------- 3 files changed, 30 insertions(+), 14 deletions(-) create mode 100755 scripts/document.sh 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 From 4b27576acc55b6e887939d8963bda2fe61a1cded Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Sat, 21 Dec 2024 17:31:41 +0900 Subject: [PATCH 6/7] refactor: using mkdocs tox environment to publish the documentation. Signed-off-by: Yuki Ito --- .github/workflows/publish-document.yml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/.github/workflows/publish-document.yml b/.github/workflows/publish-document.yml index 4286478..590def7 100644 --- a/.github/workflows/publish-document.yml +++ b/.github/workflows/publish-document.yml @@ -28,9 +28,7 @@ jobs: 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 + - name: Install mkdocs dependencies + run: pip install tox + - name: Deploy documentation to GitHub Pages + run: tox -e docs -- gh-deploy --force From 68dee06fce0a4b7eb9f0316c69840cd2fe1c53f1 Mon Sep 17 00:00:00 2001 From: Yuki Ito Date: Sat, 21 Dec 2024 17:42:49 +0900 Subject: [PATCH 7/7] doc: updating documentation setup guide. Signed-off-by: Yuki Ito --- CONTRIBUTING.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cde09b..d50bb27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,25 +156,27 @@ 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 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. -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. +To build the documentation based on your current codes, run the following command. This will outputs the documentation into `./site` folder. ```bash -pip install mkdocs-material -pip install 'mkdocstrings[python]' +tox -e docs ``` -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. +To run other mkdocs command, ```bash -mkdocs serve +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