docs: automated sphinx documentation for python bindings (#714)

---------

Co-authored-by: dante <[email protected]>
Co-authored-by: Ethan Cemer <[email protected]>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.github/workflows/pypi.yml

@@ -128,6 +128,7 @@ jobs:
           mv Cargo.lock Cargo.lock.orig
           sed "s/0\\.0\\.0/${RELEASE_TAG//v}/" Cargo.lock.orig >Cargo.lock
 
+
       - name: Install required libraries
         shell: bash
         run: |
@@ -359,3 +360,17 @@ jobs:
         with:
           repository-url: https://test.pypi.org/legacy/
           packages-dir: ./
+
+  doc-publish:
+    name: Trigger ReadTheDocs Build
+    runs-on: ubuntu-latest
+    needs: pypi-publish
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Trigger RTDs build
+        uses: dfm/rtds-action@v1
+        with:
+          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
+          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
+          commit_ref: ${{ github.ref_name }}

.github/workflows/tagging.yml

@@ -14,6 +14,40 @@ jobs:
       - uses: actions/checkout@v4
       - name: Bump version and push tag
         id: tag_version
-        uses: mathieudutour/github-tag-action@v6.1
+        uses: mathieudutour/github-tag-action@v6.2
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set Cargo.toml version to match github tag for docs
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ steps.tag_version.outputs.new_tag }}
+        run: |
+          mv docs/python/src/conf.py docs/python/src/conf.py.orig
+          sed "s/0\\.0\\.0/${RELEASE_TAG//v}/" docs/python/src/conf.py.orig >docs/python/src/conf.py
+          rm docs/python/src/conf.py.orig
+          mv docs/python/requirements-docs.txt docs/python/requirements-docs.txt.orig
+          sed "s/0\\.0\\.0/${RELEASE_TAG//v}/" docs/python/requirements-docs.txt.orig >docs/python/requirements-docs.txt
+          rm docs/python/requirements-docs.txt.orig
+
+      - name: Commit files and create tag
+        env:
+          RELEASE_TAG: ${{ steps.tag_version.outputs.new_tag }}
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git fetch --tags
+          git checkout -b release-$RELEASE_TAG
+          git add .
+          git commit -m "ci: update version string in docs"
+          git tag -d $RELEASE_TAG
+          git tag $RELEASE_TAG
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        env:
+          RELEASE_TAG: ${{ steps.tag_version.outputs.new_tag }}
+        with:
+          branch: release-${{ steps.tag_version.outputs.new_tag }}
+          force: true
+          tags: true

.gitignore

@@ -49,4 +49,5 @@ node_modules
 timingData.json
 !tests/wasm/pk.key
 !tests/wasm/vk.key
-!tests/wasm/vk_aggr.key
+docs/python/build
+!tests/wasm/vk_aggr.key

.python-version

@@ -0,0 +1 @@
+3.12.1

.readthedocs.yaml

@@ -0,0 +1,26 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: ./docs/python/src/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: ./docs/python/requirements-docs.txt

docs/python/build.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+sphinx-build ./src build

docs/python/requirements-docs.txt

@@ -0,0 +1,4 @@
+ezkl==0.0.0
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-napoleon

docs/python/src/conf.py

@@ -0,0 +1,29 @@
+import ezkl
+
+project = 'ezkl'
+release = '0.0.0'
+version = release
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
+]
+
+autosummary_generate = True
+autosummary_imported_members = True
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/python/src/index.rst

@@ -0,0 +1,11 @@
+.. extension documentation master file, created by
+   sphinx-quickstart on Mon Jun 19 15:02:05 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+ezkl python bindings
+================================================
+
+.. automodule:: ezkl
+   :members:
+   :undoc-members:

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["maturin>=0.14,<0.15"]
+requires = ["maturin>=1.0,<2.0"]
 build-backend = "maturin"
 
 [tool.pytest.ini_options]

requirements.txt

@@ -2,7 +2,7 @@ attrs==23.2.0
 exceptiongroup==1.2.0
 importlib-metadata==7.1.0
 iniconfig==2.0.0
-maturin==1.5.0
+maturin==1.5.1
 packaging==24.0
 pluggy==1.4.0
 pytest==8.1.1
@@ -11,4 +11,4 @@ typing-extensions==4.10.0
 zipp==3.18.1
 onnx==1.15.0
 onnxruntime==1.17.1
-numpy==1.26.4
+numpy==1.26.4