Merge pull request #49 from IBM/docs

Docs

.devcontainer/devcontainer.json

@@ -24,7 +24,9 @@
 				"ms-python.isort",
 				"visualstudioexptteam.vscodeintellicode",
 				"visualstudioexptteam.intellicode-api-usage-examples",
-				"VisualStudioExptTeam.vscodeintellicode"
+				"VisualStudioExptTeam.vscodeintellicode",
+				"redhat.vscode-yaml",
+				"njpwerner.autodocstring"
 			],
 			"settings": {
 				"terminal.integrated.shell.linux": "bash",
@@ -44,12 +46,23 @@
 				"isort.args": [
 					"--profile",
 					"black"
-				]
+				],
+				"yaml.schemas": {
+					"https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+				},
+				"yaml.customTags": [
+					"!ENV scalar",
+					"!ENV sequence",
+					"tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+					"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+					"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+				],
+				"autoDocstring.docstringFormat": "numpy"
 			}
 		}
 	},
 	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "pip install --upgrade pip; pip install --user -r requirements.txt; pip install -e '.[dev]'"
+	"postCreateCommand": "pip install --upgrade pip; pip install --user -r requirements.txt; pip install -e '.[dev, docs]'"
 	// "containerEnv": {},
 	// Features to add to the dev container. More info: https://containers.dev/features.
 	// "features": {},

.github/workflows/gh-pages.yml

@@ -0,0 +1,25 @@
+name: gh-pages
+on:
+  push:
+    branches:
+      - docs
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocstrings-python
+      - run: mkdocs gh-deploy --force

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 International Business Machines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/api_reference.md

@@ -0,0 +1,3 @@
+## mlflow_watsonml.WatsonMLDeploymentClient
+
+::: mlflow_watsonml.deploy.WatsonMLDeploymentClient

docs/credentials.md

@@ -0,0 +1,61 @@
+# Getting started
+
+## Setting up Credentials
+
+The best way to setup the credentials is to create a `.env` file and load it as environment variables.
+
+!!! note
+
+    ONLY USE THE CASE THAT APPLIES TO YOU IN YOUR .env FILE
+    COPYING ALL CASES CAN OVERWRITE CREDENTIALS AND MAY LEAD TO UNEXPECTED CONNECTION
+
+Refer to the following links for setting up the credentials -
+
+### [Cloud Pak for Data as a Service](https://ibm.github.io/watson-machine-learning-sdk/setup_cloud.html#authentication)
+
+- Case 0: Using a WML Credentials JSON file
+```
+WML_CREDENTIALS_FILE="/path/to/wml_credentials.json"
+```
+
+- Case 1: Using API Key
+```
+APIKEY="<wml api key>"
+LOCATION="<deployment location>"
+URL="https://${LOCATION}.ml.cloud.ibm.com"
+```
+
+- Case 2: Using Token
+```
+TOKEN="<wml token>"
+LOCATION="<deployment location>"
+URL="https://${LOCATION}.ml.cloud.ibm.com"
+```
+
+### [Cloud Pak for Data](https://ibm.github.io/watson-machine-learning-sdk/setup_cpd.html#authentication)
+- Case 3: Using Username and Password
+```
+USERNAME="<CP4D Account Username>"
+PASSWORD="<CP4D Account Password>"
+URL="<CP4D Web URL>"
+INSTANCE_ID="openshift"
+VERSION="4.6"
+```
+
+
+- Case 4: Using Username and API Key
+```
+USERNAME="<CP4D Account Username>"
+APIKEY="<CP4D Account API Key>"
+URL="<CP4D Web URL>"
+INSTANCE_ID="openshift"
+VERSION="4.6"
+```
+
+- Case 5: Using Access Token from CP4D notebook environment
+```
+TOKEN=${USER_ACCESS_TOKEN}
+URL="<CP4D Web URL>"
+INSTANCE_ID="openshift"
+VERSION="4.6"
+```

docs/index.md

@@ -0,0 +1,11 @@
+---
+hide:
+  - navigation
+---
+# Mlflow-WatsonML
+---
+
+A plugin that integrates IBM's [WatsonML](https://ibm.github.io/watson-machine-learning-sdk/) with [mlflow](https://mlflow.org).
+```mlflow_watsonml``` enables users to deploy mlflow models into IBM Cloud.
+
+Command line APIs of the plugin (also accessible through mlflow's python package) makes the deployment process seamless.

docs/install.md

@@ -0,0 +1,30 @@
+# Getting started
+
+## Installation
+
+### with pip <small>recommended</small>
+
+Mlflow-WatsonML is published as a [Python package](https://pypi.org/project/mlflow-watsonml/) and can be installed with
+`pip`, ideally by using a virtual environment. Open up a terminal and install
+Mlflow-WatsonML with:
+
+``` bash
+pip install mlflow-watsonml
+```
+
+### with git
+
+Mlflow-WatsonML can be directly used from [GitHub](https://github.com/IBM/mlflow-watsonml) by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:
+
+```bash
+git clone https://github.com/IBM/mlflow-watsonml.git
+```
+
+Next, install the library and it's dependencies with:
+
+```bash
+pip install -e mlflow-watsonml
+```
+
+
+

mkdocs.yml

@@ -0,0 +1,77 @@
+site_name: Mlflow-WatsonML
+repo_url: https://github.com/IBM/mlflow-watsonml
+repo_name: IBM/mlflow-watsonml
+copyright: Copyright © 2023 - 2024 IBM Research
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.instant.prefetch
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.footer
+    - content.code.copy
+  font:
+    text: IBM Plex Sans
+    code: IBM Plex Mono
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+plugins:
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [mlflow_watsonml] # search packages in the src folder
+          options:
+            docstring_style: numpy
+
+extra:
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+  social:
+    - icon: fontawesome/solid/paper-plane
+      link: mailto:dhruv.shah@ibm.com
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Installation: install.md
+      - Set Up Credentials: credentials.md
+  - User Guide: user_guide.md
+  - API Reference: api_reference.md

mlflow_watsonml/__init__.py

@@ -0,0 +1 @@
+from mlflow_watsonml.deploy import WatsonMLDeploymentClient

mlflow_watsonml/config.py

@@ -1,14 +1,12 @@
 import json
-import logging
 import os
 from typing import Dict, Optional
 
 from dotenv import load_dotenv
 from mlflow import MlflowException
 from mlflow.protos.databricks_pb2 import INVALID_PARAMETER_VALUE
 
-LOGGER = logging.getLogger(__name__)
-LOGGER.setLevel(logging.INFO)
+from mlflow_watsonml.logging import LOGGER
 
 WML_CREDENTIALS = "wml_credentials"
 WML_CREDENTIALS_FILE = "wml_credentials_file"
@@ -24,8 +22,17 @@
 
 class Config(dict):
     def __init__(self, config: Optional[Dict[str, str]] = None):
-        """
-        Initializes constants from input `config`, `.env` file or environment variables
+        """Initializes constants from input `config`, `.env` file or environment variables
+
+        Parameters
+        ----------
+        config : Optional[Dict[str, str]], optional
+            wml credentials, by default None
+
+        Raises
+        ------
+        MlflowException
+            missing credentials
         """
         super().__init__()
 

mlflow_watsonml/deploy.py

@@ -6,11 +6,7 @@
 from ibm_watson_machine_learning.client import APIClient
 from mlflow.deployments import BaseDeploymentClient
 from mlflow.exceptions import MlflowException
-from mlflow.protos.databricks_pb2 import (
-    ENDPOINT_NOT_FOUND,
-    INVALID_PARAMETER_VALUE,
-    NOT_IMPLEMENTED,
-)
+from mlflow.protos.databricks_pb2 import ENDPOINT_NOT_FOUND, INVALID_PARAMETER_VALUE
 
 from mlflow_watsonml.config import Config
 from mlflow_watsonml.logging import LOGGER
@@ -31,7 +27,6 @@ def target_help():
 
 
 def run_local(name, model_uri, flavor=None, config=None):
-    # TODO: implement
     raise MlflowException("mlflow-watsonml does not currently support run_local.")
 
 
@@ -42,12 +37,17 @@ def __init__(self, target_uri: str = "watsonml", config: Optional[Dict] = None):
         the plugin will try to search for WML credentials in `.env` file or the
         environment variables.
 
+        Refer to the following links for setting up the credentials -
+
+        1. [Cloud Pak for Data as a Service](https://ibm.github.io/watson-machine-learning-sdk/setup_cloud.html#authentication)
+        2. [Cloud Pak for Data](https://ibm.github.io/watson-machine-learning-sdk/setup_cpd.html#authentication)
+
         Parameters
         ----------
         target_uri : str, optional
-            target uri for mlflow deployment, by default "watsonml"
+            Target URI for mlflow deployment, by default "watsonml"
         config : Optional[Dict], optional
-            wml credentials, by default None
+            WML Credentials, by default None
         """
         super().__init__(target_uri)
 

mlflow_watsonml/store.py

@@ -18,20 +18,20 @@ def store_or_update_model(
     software_spec_uid: str,
     model_id: Optional[str] = None,
 ) -> Tuple[str, str]:
-    """Store model_object in a WML repository
+    """Store or update a model object in a WML repository
 
     Parameters
     ----------
     client : APIClient
         WML client
     model_object : Any
-        artifact object
+        model object
     model_name : str
         name of the model
     model_type : str
         type of model
     software_spec_uid : str
-        uid of software specification
+        UID of software specification
     model_id : str, optional
         asset id of the model to be updated
         by default None
@@ -98,7 +98,7 @@ def store_or_update_function(
     software_spec_uid: str,
     function_id: Optional[str] = None,
 ) -> Tuple[str, str]:
-    """Store or update function in WML repository
+    """Store or update a python function in WML repository
 
     Parameters
     ----------

setup.py

@@ -20,6 +20,7 @@
     extras_require={
         "dev": ["ipython", "black", "pytest", "build", "wheel", "twine", "pytest-cov"],
         "onnx": ["onnx", "onnxruntime"],
+        "docs": ["mkdocs", "mkdocstrings-python", "mkdocs-material"],
     },
     entry_points={"mlflow.deployments": "watsonml=mlflow_watsonml.deploy"},
     python_requires=">=3.9",