v1.0.2

Added first pass at documentation

config/package.json

@@ -1,4 +1,4 @@
 {
     "name": "kitops",
-    "version": "1.0.1"
+    "version": "1.0.2"
 }

docs/explanation.md

@@ -0,0 +1,15 @@
+This part of the project documentation focuses on an
+**understanding-oriented** approach. You'll get a
+chance to read about the background of the project,
+as well as reasoning about how it was implemented.
+
+> **Note:** Expand this section by considering the
+> following points:
+
+- Give context and background on your library
+- Explain why you created it
+- Provide multiple examples and approaches of how
+    to work with it
+- Help the reader make connections
+- Avoid writing instructions or technical descriptions
+    here

docs/how-to-guides.md

@@ -0,0 +1,66 @@
+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/index.md

@@ -0,0 +1,19 @@
+This site contains the project documentation for the
+`KitOps Manager` project. Its aim is to provide a python library for
+easily working with [KitOps' ModelKits](https://kitops.ml).
+
+## Table Of Contents
+
+The documentation follows the best practice for
+project documentation as described by Daniele Procida
+in the [Diátaxis documentation framework](https://diataxis.fr/)
+and consists of four separate parts:
+
+1. [Tutorials](tutorials.md)
+2. [How-To Guides](how-to-guides.md)
+3. [Reference](reference.md)
+4. [Explanation](explanation.md)
+
+Quickly find what you're looking for depending on
+your use case by looking at the different pages.
+

docs/reference.md

@@ -0,0 +1,6 @@
+This part of the project documentation focuses on
+an **information-oriented** approach. Use it as a
+reference for the technical implementation of the
+`kitops` project code.
+
+::: src.kitops.modelkit.kitfile.Kitfile

docs/tutorials.md

@@ -0,0 +1,16 @@
+This part of the project documentation focuses on a
+**learning-oriented** approach. You'll learn how to
+get started with the code in this project.
+
+> **Note:** Expand this section by considering the
+> following points:
+
+- Help newcomers with getting started
+- Teach readers about your library by making them
+    write code
+- Inspire confidence through examples that work for
+    everyone, repeatably
+- Give readers an immediate sense of achievement
+- Show concrete examples, no abstractions
+- Provide the minimum necessary explanation
+- Avoid any distractions

mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: KitOps Manager Documentation
+
+theme:
+  name: "material"
+
+plugins: 
+  - mkdocstrings
+
+nav:
+  - KitOps Manager Docs: index.md
+  - tutorials.md
+  - How-To Guides: how-to-guides.md
+  - reference.md
+  - explanation.md

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kitops"
-version = "1.0.1"
+version = "1.0.2"
 authors = [
   { name="Brett Hodges", email="brett@jozu.com" },
 ]

requirements/ci.in

@@ -1,2 +1,5 @@
 tox
 tox-conda
+mkdocs
+"mkdocstrings[python]"
+mkdocs-material

src/kitops/__init__.py

@@ -1,4 +1,25 @@
-__version__ = '1.0.1'
+'''
+Copyright 2024 The KitOps Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+'''
+
+"""
+Manage KitOps' ModelKits
+"""
+__version__ = '1.0.2'
 __all__ = [
      'kitfile'
  ]

src/kitops/modelkit/__init__.py

@@ -1,2 +1,20 @@
+'''
+Copyright 2024 The KitOps Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+'''
+
 from .kitfile import Kitfile
 

src/kitops/modelkit/kitfile.py

@@ -1,7 +1,30 @@
+'''
+Copyright 2024 The KitOps Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+'''
+
+"""
+Define the Kitfile class to manage KitOps ModelKits and Kitfiles.
+"""
+import copy
 import yaml
 from pathlib import Path
 from typing import Any, Dict, List, Set
 
+from .util import clean_empty_items, validate_dict
 from .validators.code_validator import CodeValidator
 from .validators.datasets_validator import DatasetsValidator
 from .validators.docs_validator import DocsValidator
@@ -20,10 +43,38 @@ class Kitfile:
 
     def __init__(self, path=None):
         """
-        Initialize the Kitfile.
+        Initialize the Kitfile from a path to an existing Kitfile, or 
+        create an empty Kitfile.
+
+        Examples:
+            >>> kitfile = Kitfile(path="path/to/Kitfile")
+            >>> kitfile.to_yaml()
+
+            >>> kitfile = Kitfile()
+            >>> kitfile.manifestVersion = "1.0"
+            >>> kitfile.package = {"name": "my_package", "version": "0.1.0",
+            ...                    "description": "My package description",
+            ...                    "authors": ["Author 1", "Author 2"]}
+            >>> kitfile.code = [{"path": "code/", "description": "Code description",
+            ...                  "license": "Apache-2.0"}]
+            >>> kitfile.datasets = [{"name": "my_dataset", "path": "datasets/",
+            ...                      "description": "Dataset description",
+            ...                      "license": "Apache-2.0"}]
+            >>> kitfile.docs = [{"path": "docs/", "description": "Docs description"}]
+            >>> kitfile.model = {"name": "my_model", "path": "model/",
+            ...                  "framework": "tensorflow", "version": "2.0.0",
+            ...                  "description": "Model description",
+            ...                  "license": "Apache-2.0", "parts": [],
+            ...                  "parameters": ""}
+            >>> kitfile.to_yaml()
+            'manifestVersion: 1.0\npackage:\n  name: my_package\n  version: 0.1.0\n  description: My package description\n  authors:\n  - Author 1\n  - Author 2\ncode:\n- path: code/\n  description: Code description\n  license: Apache-2.0\ndatasets:\n- name: my_dataset\n  path: datasets/\n  description: Dataset description\n  license: Apache-2.0\ndocs:\n- path: docs/\n  description: Docs description\nmodel:\n  name: my_model\n  path: model/\n  framework: tensorflow\n  version: 2.0.0\n  description: Model description\n  license: Apache-2.0\n  parts: []\n  parameters: ''\n'
+
 
         Args:
-            path (str, optional): Path to the Kitfile. Defaults to None.
+            path (str, optional): Path to existing Kitfile to load. Defaults to None.
+
+        Returns:
+            Kitfile: Kitfile object.
         """
         self._data = {}
         self._kitfile_allowed_keys = {'manifestVersion', 'package', 
@@ -77,7 +128,7 @@ def initialize_kitfile_section_validators(self):
 
     def load_from_file(self, path):
         """
-        Load Kitfile data from a file.
+        Load Kitfile data from a yaml-formatted file.
 
         Args:
             path (str): Path to the Kitfile.
@@ -102,8 +153,8 @@ def load_from_file(self, path):
                 raise
 
         try:
-            self.validate_dict(value=data, 
-                               allowed_keys=self._kitfile_allowed_keys)
+            validate_dict(value=data, 
+                          allowed_keys=self._kitfile_allowed_keys)
         except ValueError as e:
             raise ValueError(
                     "Kitfile must be a dictionary with allowed " +
@@ -122,23 +173,6 @@ def validate_and_set_attributes(self, data: Dict[str, Any]):
         for key, value in data.items():
             self.__setattr__(key, value)
 
-    def validate_dict(self, value: Any, allowed_keys: Set[str]):
-        """
-        Validate a dictionary against allowed keys.
-
-        Args:
-            value (Any): Value to validate.
-            allowed_keys (Set[str]): Set of allowed keys.
-        """
-        if not isinstance(value, dict):
-            raise ValueError(
-                    f"Expected a dictionary but got {type(value).__name__}")
-        value_keys = set(value.keys())
-        unallowed_keys = value_keys.difference(allowed_keys) 
-        if len(unallowed_keys) > 0:
-            raise ValueError("Found unallowed key(s): " +
-                             f"{', '.join(unallowed_keys)}")
-
     @property
     def manifestVersion(self) -> str:
         """
@@ -264,13 +298,21 @@ def model(self, value: Dict[str, Any]):
         """
         self._model_validator.validate(data=value)
         self._data["model"] = value
-
-    def to_yaml(self) -> str:
+        
+    def to_yaml(self, suppress_empty_values: bool = True) -> str:
         """
-        Serialize the Kitfile to YAML format.
+        Serialize the Kitfile to YAML format. 
 
+        Args:
+            suppress_empty_values (bool, optional): Whether to suppress 
+                empty values. Defaults to True.
         Returns:
             str: YAML representation of the Kitfile.
         """
-        return yaml.dump(data = self._data, sort_keys=False,
+        dict_to_print = self._data
+        if suppress_empty_values:
+            dict_to_print = copy.deepcopy(self._data)
+            dict_to_print = clean_empty_items(dict_to_print)
+
+        return yaml.dump(data = dict_to_print, sort_keys=False,
                          default_flow_style=False)