From 3c30cd208bedb6f4436bab5a4f0fba77c7b80da5 Mon Sep 17 00:00:00 2001 From: Gorkem Ercan Date: Tue, 10 Dec 2024 08:38:22 -0500 Subject: [PATCH] Update pykitops documentation (#653) Update pykitops documentation to reflect commit 3a6bbd73811e0c9960f91f42ef5717b780c044f7 in repository https://github.com/jozu-ai/pykitops Co-authored-by: amisevsk <16168279@users.noreply.github.com> --- docs/src/docs/pykitops/before-you-begin.md | 61 ++++++++++++++++++ docs/src/docs/pykitops/how-to-guides.md | 64 +++++++++++++++++++ docs/src/docs/pykitops/index.md | 7 ++ docs/src/docs/pykitops/reference/index.md | 5 ++ docs/src/docs/pykitops/reference/kit.md | 48 ++++++++++++++ docs/src/docs/pykitops/reference/kitfile.md | 9 +++ docs/src/docs/pykitops/reference/manager.md | 9 +++ docs/src/docs/pykitops/reference/reference.md | 9 +++ docs/src/docs/pykitops/reference/user.md | 9 +++ 9 files changed, 221 insertions(+) create mode 100644 docs/src/docs/pykitops/before-you-begin.md create mode 100644 docs/src/docs/pykitops/how-to-guides.md create mode 100644 docs/src/docs/pykitops/index.md create mode 100644 docs/src/docs/pykitops/reference/index.md create mode 100644 docs/src/docs/pykitops/reference/kit.md create mode 100644 docs/src/docs/pykitops/reference/kitfile.md create mode 100644 docs/src/docs/pykitops/reference/manager.md create mode 100644 docs/src/docs/pykitops/reference/reference.md create mode 100644 docs/src/docs/pykitops/reference/user.md diff --git a/docs/src/docs/pykitops/before-you-begin.md b/docs/src/docs/pykitops/before-you-begin.md new file mode 100644 index 00000000..543aa088 --- /dev/null +++ b/docs/src/docs/pykitops/before-you-begin.md @@ -0,0 +1,61 @@ +# Before You Begin + +This project was created using Python v3.12, but works with Python versions >= 3.10. + +### 1/ Install the Kit CLI + +The PyKitOps SDK uses the Kit CLI to manage ModelKits so you'll need an up-to-date Kit CLI version on your machine. + +To determine if the Kit CLI is installed in your environment: +1. Open a Terminal window +1. Run the following command: + + ```bash + kit version + ``` + +1. You should see output similar to the following: + + ``` + Version: 0.4.0 + Commit: e2e83d953823ac35648f2f76602a0cc6e8ead819 + Built: 2024-11-05T20:29:07Z + Go version: go1.22.6 + ``` + +If you don't have the Kit CLI installed, follow the [Kit Installation Instructions](https://kitops.ml/docs/cli/installation.html). + +### 2/ Prepare Your Registry + +To get the most out of ModelKits we strongly suggest you [sign up for a free account at Jozu.ml](https://api.jozu.ml/signup). + +The [Jozu Hub](https://jozu.ml/) will: +* Automatically generates a container from a ModelKit +* Show you details about the various parts of your ModelKit at a glance +* Indicate whether ModelKits are signed + +Alternatively, ModelKits can be stored in any OCI 1.1-compliant container registry, however, you'll need to set the `JOZU_REGISTRY` environment variable in addition to the username, password, and namespace (see the next section for details). + +### 3/ Set Your Environment + +1. In the root directory of your project (the *"Project directory"*) create a `.env` file. +1. Edit the `.env` file by adding an entry for your `JOZU_USERNAME`, your `JOZU_PASSWORD` and your `JOZU_NAMESPACE` (this should match the repository name you'll be pushing to in the regsitry). If you're *not* using the Jozu Hub you'll also need to set the `JOZU_REGISTRY` variable to point to the URL for your registry. + + An example `.env` file for Jozu Hub will look like this: + + JOZU_USERNAME=brett@jozu.org + JOZU_PASSWORD=my_password + JOZU_NAMESPACE=brett + + An example `.env` file for another registry will look like this: + + JOZU_REGISTRY=hub.docker.com + JOZU_USERNAME=brett@jozu.org + JOZU_PASSWORD=my_password + JOZU_NAMESPACE=brett + + - The Kitops Manager uses the entries in the `.env` file to login to [Jozu.ml](https://www.jozu.ml). + - As an alternative to using a `.env` file, you can create Environment Variables for each of the entries above. +1. Be sure to save the changes to your .env file before continuing. + +That's it! You can check out the How To Guide to see an example of how to use the SDK. diff --git a/docs/src/docs/pykitops/how-to-guides.md b/docs/src/docs/pykitops/how-to-guides.md new file mode 100644 index 00000000..c15181b6 --- /dev/null +++ b/docs/src/docs/pykitops/how-to-guides.md @@ -0,0 +1,64 @@ +This part of the project documentation focuses on a **problem-oriented** approach. You'll tackle common tasks that you might have, with the help of the code provided in this project. + +## How To Create A Kitfile Object? + +Whether you're working with an existing ModelKit's Kitfile, +or starting from nothing, the `kitops` package can help you +get this done. + +Install the `kitops` package from PYPI into your project's environment +with the following command + +``` +pip install kitops +``` + +Inside of your code you can now import the `Kitfile` +class from the `kitops.modelkit.kitfile` module: + + # your code + from kitops.modelkit.kitfile import Kitfile + +After you've imported the class, you can use it +to create a Kitfile object from an existing ModelKit's Kitfile: + + # your code + from kitops.modelkit.kitfile import Kitfile + + my_kitfile = Kitfile(path='/path/to/Kitfile') + print(my_kitfile.to_yaml()) + + # The output should match the contents of the Kitfile + # located at: /path/to/Kitfile + +You can also create an empty Kitfile from scratch: + + # your code + from kitops.modelkit.kitfile import Kitfile + + my_kitfile = Kitfile() + print(my_kitfile.to_yaml()) + + # OUTPUT: {} + +Regardless of how you created the Kitfile, you can update its contents +like you would do with any other python dictionary: + + # your code + my_kitfile.manifestVersion = "3.0" + my_kitfile.package = { + "name": "Another-Package", + "version": "3.0.0", + "description": "Another description", + "authors": ["Someone"] + } + print(my_kitfile.to_yaml()) + + # OUTPUT: + # manifestVersion: '3.0' + # package: + # name: Another-Package + # version: 3.0.0 + # description: Another description + # authors: + # - Someone diff --git a/docs/src/docs/pykitops/index.md b/docs/src/docs/pykitops/index.md new file mode 100644 index 00000000..ac00e5d7 --- /dev/null +++ b/docs/src/docs/pykitops/index.md @@ -0,0 +1,7 @@ +This site contains the project documentation for the PyKitOps SDK project - a python library for working with [KitOps' ModelKits](https://kitops.ml) in code. You can find [KitOps and ModelKit documentation](https://kitops.ml/docs/overview.html) on the KitOps site. + +## PyKitOps Documentation + +1. [Before You Begin](before-you-begin.md) +2. [How-To Guides](how-to-guides.md) +3. [API Reference](reference/index.md) diff --git a/docs/src/docs/pykitops/reference/index.md b/docs/src/docs/pykitops/reference/index.md new file mode 100644 index 00000000..8c0c7e65 --- /dev/null +++ b/docs/src/docs/pykitops/reference/index.md @@ -0,0 +1,5 @@ +# Reference + +This is the reference or code API. It includes the classes, functions, +parameters, attributes, and all of the parts of KitOps you can use in your +application. diff --git a/docs/src/docs/pykitops/reference/kit.md b/docs/src/docs/pykitops/reference/kit.md new file mode 100644 index 00000000..d1b9e160 --- /dev/null +++ b/docs/src/docs/pykitops/reference/kit.md @@ -0,0 +1,48 @@ +# kit Commands + +These functions provide programmatic access to the KitOps Command-Line Interface. + +Available commands include: + +* `info()` +* `inspect()` +* `list()` +* `login()` +* `logout()` +* `pack()` +* `pull()` +* `push()` +* `remove()` +* `tag()` +* `unpack()` +* `version()` + +You can import them all from `kitops.cli.kit` + +```python +import kitops.cli.kit as kit +``` + +:::kitops.cli.kit.info + +:::kitops.cli.kit.inspect + +:::kitops.cli.kit.list + +:::kitops.cli.kit.login + +:::kitops.cli.kit.logout + +:::kitops.cli.kit.pack + +:::kitops.cli.kit.pull + +:::kitops.cli.kit.push + +:::kitops.cli.kit.remove + +:::kitops.cli.kit.tag + +:::kitops.cli.kit.unpack + +:::kitops.cli.kit.version \ No newline at end of file diff --git a/docs/src/docs/pykitops/reference/kitfile.md b/docs/src/docs/pykitops/reference/kitfile.md new file mode 100644 index 00000000..4d796317 --- /dev/null +++ b/docs/src/docs/pykitops/reference/kitfile.md @@ -0,0 +1,9 @@ +# `Kitfile` class + +You can import the `Kitfile` class from `kitops.modelkit.kitfile`: + +```python +from kitops.modelkit.kitfile import Kitfile +``` + +::: kitops.modelkit.kitfile.Kitfile \ No newline at end of file diff --git a/docs/src/docs/pykitops/reference/manager.md b/docs/src/docs/pykitops/reference/manager.md new file mode 100644 index 00000000..1ee17194 --- /dev/null +++ b/docs/src/docs/pykitops/reference/manager.md @@ -0,0 +1,9 @@ +# `ModelKitManager` class + +You can import the `ModelKitManager` class from `kitops.modelkit.manager`: + +```python +from kitops.modelkit.manager import ModelKitManager +``` + +::: kitops.modelkit.manager.ModelKitManager \ No newline at end of file diff --git a/docs/src/docs/pykitops/reference/reference.md b/docs/src/docs/pykitops/reference/reference.md new file mode 100644 index 00000000..ce012ac2 --- /dev/null +++ b/docs/src/docs/pykitops/reference/reference.md @@ -0,0 +1,9 @@ +# `ModelKitReference` class + +You can import the `ModelKitReference` class from `kitops.modelkit.reference`: + +```python +from kitops.modelkit.reference import ModelKitReference +``` + +::: kitops.modelkit.reference.ModelKitReference \ No newline at end of file diff --git a/docs/src/docs/pykitops/reference/user.md b/docs/src/docs/pykitops/reference/user.md new file mode 100644 index 00000000..8e018749 --- /dev/null +++ b/docs/src/docs/pykitops/reference/user.md @@ -0,0 +1,9 @@ +# `UserCredentials` class + +You can import the `UserCredentials` class from `kitops.modelkit.user`: + +```python +from kitops.modelkit.user import UserCredentials +``` + +::: kitops.modelkit.user.UserCredentials \ No newline at end of file