From 9b88e6e9b587b1df35b4822370c4bb07d0f3e7ae Mon Sep 17 00:00:00 2001 From: Murph Murphy Date: Wed, 15 Nov 2023 12:14:25 -0700 Subject: [PATCH 1/3] 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 | 1 + core/python/cloaked-ai/.readthedocs.yaml | 18 +++++++ core/python/cloaked-ai/RELEASING.md | 6 ++- core/python/cloaked-ai/docs/api-reference.md | 50 +++++++++++++++++++ core/python/cloaked-ai/docs/index.md | 14 ++++++ .../cloaked-ai/docs/stylesheets/extra.css | 6 +++ core/python/cloaked-ai/mkdocs.yml | 46 +++++++++++++++++ core/python/cloaked-ai/pyproject.toml | 18 ++++++- .../cloaked-ai/rust-toolchain-from-file.sh | 26 ++++++++++ 9 files changed, 182 insertions(+), 3 deletions(-) create mode 100644 core/python/cloaked-ai/.gitignore create mode 100644 core/python/cloaked-ai/.readthedocs.yaml create mode 100644 core/python/cloaked-ai/docs/api-reference.md create mode 100644 core/python/cloaked-ai/docs/index.md create mode 100644 core/python/cloaked-ai/docs/stylesheets/extra.css create mode 100644 core/python/cloaked-ai/mkdocs.yml create mode 100755 core/python/cloaked-ai/rust-toolchain-from-file.sh diff --git a/core/python/cloaked-ai/.gitignore b/core/python/cloaked-ai/.gitignore new file mode 100644 index 0000000..1320f90 --- /dev/null +++ b/core/python/cloaked-ai/.gitignore @@ -0,0 +1 @@ +site diff --git a/core/python/cloaked-ai/.readthedocs.yaml b/core/python/cloaked-ai/.readthedocs.yaml new file mode 100644 index 0000000..ec7b816 --- /dev/null +++ b/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 + + diff --git a/core/python/cloaked-ai/RELEASING.md b/core/python/cloaked-ai/RELEASING.md index 99fc455..fe2f0f3 100644 --- a/core/python/cloaked-ai/RELEASING.md +++ b/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 diff --git a/core/python/cloaked-ai/docs/api-reference.md b/core/python/cloaked-ai/docs/api-reference.md new file mode 100644 index 0000000..de8a40f --- /dev/null +++ b/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 diff --git a/core/python/cloaked-ai/docs/index.md b/core/python/cloaked-ai/docs/index.md new file mode 100644 index 0000000..1affb4a --- /dev/null +++ b/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" +] +``` diff --git a/core/python/cloaked-ai/docs/stylesheets/extra.css b/core/python/cloaked-ai/docs/stylesheets/extra.css new file mode 100644 index 0000000..c68f71e --- /dev/null +++ b/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); +} \ No newline at end of file diff --git a/core/python/cloaked-ai/mkdocs.yml b/core/python/cloaked-ai/mkdocs.yml new file mode 100644 index 0000000..cebd427 --- /dev/null +++ b/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: | + © 2023 IronCore Labs, Inc. diff --git a/core/python/cloaked-ai/pyproject.toml b/core/python/cloaked-ai/pyproject.toml index 5f8d0bd..306f1a5 100644 --- a/core/python/cloaked-ai/pyproject.toml +++ b/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}" diff --git a/core/python/cloaked-ai/rust-toolchain-from-file.sh b/core/python/cloaked-ai/rust-toolchain-from-file.sh new file mode 100755 index 0000000..55da73d --- /dev/null +++ b/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" From 924760a64b45d5bb239c3f1450d69a0f216ebf0d Mon Sep 17 00:00:00 2001 From: Leeroy Travis Date: Wed, 15 Nov 2023 19:28:07 +0000 Subject: [PATCH 2/3] Set release version 0.4.4-rc.21 [skip ci] --- Cargo.lock | 2 +- core/Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 6b03783..376ebfa 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -468,7 +468,7 @@ checksum = "702fc72eb24e5a1e48ce58027a675bc24edd52096d5397d4aea7c6dd9eca0bd1" [[package]] name = "cloaked-ai" -version = "0.4.4-pre.21" +version = "0.4.4-rc.21" dependencies = [ "aes-gcm", "aes-siv", diff --git a/core/Cargo.toml b/core/Cargo.toml index 5948ef5..cca7b00 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "cloaked-ai" -version = "0.4.4-pre.21" +version = "0.4.4-rc.21" edition = "2021" [dependencies] From f55c7e4efacf39d6f9f61dabdb4e27bd7c54965d Mon Sep 17 00:00:00 2001 From: Leeroy Travis Date: Wed, 15 Nov 2023 19:28:09 +0000 Subject: [PATCH 3/3] Bump to next development version 0.4.4-pre.22 [skip ci] --- Cargo.lock | 2 +- core/Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 376ebfa..a302df7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -468,7 +468,7 @@ checksum = "702fc72eb24e5a1e48ce58027a675bc24edd52096d5397d4aea7c6dd9eca0bd1" [[package]] name = "cloaked-ai" -version = "0.4.4-rc.21" +version = "0.4.4-pre.22" dependencies = [ "aes-gcm", "aes-siv", diff --git a/core/Cargo.toml b/core/Cargo.toml index cca7b00..c6be152 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "cloaked-ai" -version = "0.4.4-rc.21" +version = "0.4.4-pre.22" edition = "2021" [dependencies]