Update pykitops documentation (#653)

Update pykitops documentation to reflect commit 3a6bbd73811e0c9960f91f42ef5717b780c044f7
in repository https://github.com/jozu-ai/pykitops

Co-authored-by: amisevsk <[email protected]>

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:
+   
+        [email protected]
+        JOZU_PASSWORD=my_password
+        JOZU_NAMESPACE=brett
+
+    An example `.env` file for another registry will look like this:
+        
+        JOZU_REGISTRY=hub.docker.com
+        [email protected]
+        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.

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

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)

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.

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

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

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

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

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