Set up python documentation generation (#1)

* Attempt at using readthedocs

* Remove unused requirements file

We're using hatch pinned versions to do the same thing

* Maybe commands all start from the top level

* Do multiline commands work?

* Accept defaults

* Pass `-y` to command, not `sh`

* Try normal bash multi-line

* Try it in a bash script

* Correct script path

* Closer to done script

* `rustup` not accessible

* Maybe we can get jq from apt

* Sudo apt

* Move more things into the script

* Make sure the downloaded jq is on the path

* Maybe /usr/local/bin is accessible

* Should be able to put it into the cargo dir we made

* Why no find

* I'm so bad at bash

* Confused

* Worked locally

* But without the duplicate. Must have been a redirect

* I think we made it past jq finally

* No `source`, it's running in `sh`

* Explicit cargo calls?

* Add error doc manually

core/python/cloaked-ai/.gitignore

@@ -0,0 +1 @@
+site

core/python/cloaked-ai/.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  commands:
+    # install rust. If we automate/otherwise committing the generated python module we can avoid rust at all and
+    # only would need to install hatch here. Doc builds would then be a few seconds instead of a few minutes.
+    - ./core/python/cloaked-ai/rust-toolchain-from-file.sh
+    - ~/.cargo/bin/cargo b --release
+    - ~/.cargo/bin/cargo run --bin uniffi-bindgen generate --library ./target/release/libcloaked_ai.so --language python  --out-dir core/python/cloaked-ai/cloaked_ai
+    # actual doc building part
+    - pip install -v "hatch==1.7.0"
+    - cd core/python/cloaked-ai && hatch run docs:build --site-dir $READTHEDOCS_OUTPUT/html
+
+

core/python/cloaked-ai/RELEASING.md

@@ -25,11 +25,15 @@ Once you have a built environment, some common `hatch` commands you may want to
 ```console
 hatch build -t wheel   # to produce .whl file for release
 hatch shell            # to get a local pyenv with the sdk installed
-hatch run test         # to run unit tests
+hatch run test:test    # to run unit tests
 ```
 
 > Note: the generate step needs debug symbols to work on Linux, don't strip them before running it (they can be stripped afterwards)
 
+## Documentation
+
+Docs can be previewed with `hatch run docs:serve`, or manually built with `hatch run docs:build`. They'll be automatically built and uploaded by our [readthedocs](https://readthedocs.com) integration.
+
 ## Release
 
 ### Manual

core/python/cloaked-ai/docs/api-reference.md

@@ -0,0 +1,50 @@
+# API Reference
+
+`CloakedAiError` documentation is not correctly generated. Its definition is included here manually:
+
+```python
+class CloakedAiError(Exception):
+    """
+    Errors related to CloakedAiStandalone
+    """
+    class InvalidConfiguration(CloakedAiError):
+        """
+        Error while loading configuration.
+        """
+    class InvalidKey(CloakedAiError):
+        """
+        Error with key used to initialize CloakedAiStandalone
+        """
+    class InvalidIv(CloakedAiError):
+        """
+        Error during decryption with provided IV
+        """
+    class InvalidAuthHash(CloakedAiError):
+        """
+        Error during decryption with provided authentication hash
+        """
+    class InvalidInput(CloakedAiError):
+        """
+        Error with input vector. Likely due to overflow with large values
+        """
+    class DocumentError(CloakedAiError):
+        """
+        Error when encrypting or decrypting documents
+        """
+    class ProtobufError(CloakedAiError):
+        """
+        Error when parsing encryption headers/metadata
+        """
+    class TenantSecurityError(CloakedAiError):
+        """
+        Error with requests to TSC
+        """
+    class IronCoreDocumentsError(CloakedAiError):
+        """
+        Error with IronCore Documents
+        """
+```
+
+Keep in mind that this manual definition may get out of step with the actual source, and refer to the source if there is any ambiguity.
+
+::: cloaked_ai.cloaked_ai

core/python/cloaked-ai/docs/index.md

@@ -0,0 +1,14 @@
+# Home
+
+This is documentation for the Python API surface. For higher level documentation visit [docs.ironcorelabs.com](https://docs.ironcorelabs.com).
+
+## Installation
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+    "ironcore-alloy"
+]
+```

core/python/cloaked-ai/docs/stylesheets/extra.css

@@ -0,0 +1,6 @@
+:root {
+  --md-primary-fg-color: rgb(15, 23, 42);
+  --md-primary-bg-color: white;
+  --md-accent-fg-color: rgb(251, 1, 0);
+  --md-accent-bg-color: rgb(209, 213, 219);
+}

core/python/cloaked-ai/mkdocs.yml

@@ -0,0 +1,46 @@
+site_name: IronCore Labs Alloy SDK
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    # https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
+    - scheme: default
+      primary: custom
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+plugins:
+- search
+- mkdocstrings:
+    default_handler: python  
+    handlers:
+        python:
+          options:
+            show_if_no_docstring: true
+            merge_init_into_class: true
+            docstring_section_style: list
+            docstring_style: numpy
+            show_category_heading: true
+            show_root_heading: true
+            show_root_toc_entry: false
+            filters:
+              - "!^_"
+extra_css:
+  - stylesheets/extra.css
+copyright: |
+  &copy; 2023 <a href="https://ironcorelabs.com" target="_blank" rel="noopener">IronCore Labs, Inc.</a>

core/python/cloaked-ai/pyproject.toml

@@ -37,10 +37,24 @@ artifacts = ["*.so", "*.dylib"]
 [tool.hatch.build.targets.wheel.hooks.custom]
 
 [tool.hatch.envs.default]
-dependencies = ["pytest", "pytest-cov", "pytest-metadata"]
 python = "3.10"
 
-[tool.hatch.envs.default.scripts]
+[tool.hatch.envs.docs]
+dependencies = ["mkdocs.material==9.4.8", "mkdocstrings-python==1.7.4"]
+
+[tool.hatch.envs.docs.scripts]
+build = "mkdocs build --clean --strict {args}"
+serve = "mkdocs serve --dev-addr localhost:8000 {args}"
+
+[tool.hatch.envs.test]
+dependencies = [
+  "pytest==7.4.2",
+  "pytest-cov==4.1.0",
+  "pytest-metadata==3.0.0",
+  "pytest-asyncio==0.21.1",
+]
+
+[tool.hatch.envs.test.scripts]
 coverage = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=cloaked_ai --cov=tests {args}"
 test = "coverage --no-cov {args}"
 

core/python/cloaked-ai/rust-toolchain-from-file.sh

@@ -0,0 +1,26 @@
+#! /usr/bin/env bash
+# Used by readthedocs to get the right version of rust installed. Based on our github action that does the same.
+# install and source rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none
+source "$HOME/.cargo/env"
+# download a jq binary and add it somewhere on the path we can write to, install other dependencies
+curl -s -L -o /home/docs/.cargo/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.7/jq-linux-amd64 && chmod +x "$HOME"/.cargo/bin/jq
+pip install yq tomlq
+# pull the rust-toolchain.toml info
+for F in rust-toolchain.toml rust-toolchain ; do
+  if [ -f "$F" ] ; then
+    TOML_FILE="$F"
+    break
+  fi
+done
+if [ -z "$TOML_FILE" ]; then
+  echo "rust-toolchain{.toml} not found, expecting explicit inputs"
+  exit 0
+fi
+TOML_TOOLCHAIN=$(tomlq -r '.toolchain.channel | select(. != null)' "$TOML_FILE")
+TOML_TARGETS=$(tomlq -r '.toolchain.targets | select(. != null) | @csv' "$TOML_FILE")
+TOML_COMPONENTS=$(tomlq -r '.toolchain.components | select(. != null) | @csv' "$TOML_FILE")
+# install what we found
+rustup toolchain install "$TOML_TOOLCHAIN""$TOML_TARGETS""$TOML_COMPONENTS" --profile minimal --no-self-update
+rustup default "$TOML_TOOLCHAIN"
+rustup override set "$TOML_TOOLCHAIN"