Update docs for release v0.3

Update the documentation to reflect the changes made for the next FuseML release. Also includes fixing some typos and formating.
fuseml · Nov 18, 2021 · 77d10be · 77d10be
1 parent 4416968
commit 77d10be
Show file tree

Hide file tree

Showing 12 changed files with 5,402 additions and 160 deletions.
diff --git a/README.md b/README.md
@@ -14,13 +14,13 @@ We are using the [material theme from squidfunk](https://squidfunk.github.io/mkd
 
 Simply run:
 
-```
+```bash
 docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
 ```
 
 ## How to build the final docs outside a docker container
 
-```
+```bash
 pip install --user mkdocs-material
 mkdocs build
 ```

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -2,8 +2,7 @@
 
 ## Our processes
 
-
-This repository is used through the entired development process. All the code is publicly available, and the code reviews are public. **Anyone** is welcome to contribute to those.
+This repository is used through the entire development process. All the code is publicly available, and the code reviews are public. **Anyone** is welcome to contribute to those.
 
 In terms of design, **anyone** is welcomed to propose requirements. Do not hesitate to share any design requirements or improvements. We will discuss them publicly in this repository. This means that any user, developer, or contributor of an eventual fork is welcomed to propose code or design changes.
 
@@ -24,17 +23,17 @@ The next step is to fork our project: [here](https://docs.github.com/en/github/g
 Then create your own branch for your bug/feature, edit the code/documentation, commit, and push your changes in your repository
 
 ```bash
-$ git checkout -b <branchname>
-$ ...
-$ git commit
-$ git push origin HEAD
+git checkout -b <branchname>
+...
+git commit
+git push origin HEAD
 ```
 
 Finally, create a pull request (using the web interface or using your favorite github client tool).
 
 Expectations for commit and pull requests are expressed below.
 
-If your contribution doesn't land immediately, you might need to rebase your change based on the branch you are targetting with your PR (e.g. `main`):
+If your contribution doesn't land immediately, you might need to rebase your change based on the branch you are targeting with your PR (e.g. `main`):
 
 ```bash
 ## Go back to the target branch (e.g. main) branch
@@ -58,7 +57,7 @@ $ git push origin HEAD -f
 - Don't send large new features in a giant commit.
 - Do not assume the reviewer understands what the original problem was, provide all the necessary tools for reviewers to do their job
 - Describe why a change is made, not how a change is made. It is encouraged to mention any limitations or problems of the current code, and how the commit is fixing those pains.
-- We are following conventional commits (https://www.conventionalcommits.org/en/v1.0.0/). Please write your commit messages appropriately.
+- We are following [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Please write your commit messages appropriately.
 
 See also: https://wiki.openstack.org/wiki/GitCommitMessages
 
@@ -100,11 +99,10 @@ We expect the maintainers to be the heralds of the good practices of this docume
 A few extra rules apply to them:
 
 - Maintainers must NOT push to existing branches without going through a PR.
-- Maintainers must NOT force merge patches. An exception can be made to unbreak tests.
-- A maintainer must regularily triage issues and review PRs
+- Maintainers must NOT force merge patches. An exception can be made to fix tests.
+- A maintainer must regularly triage issues and review PRs
 - A maintainer is responsible to enforce the code of conduct.
 
 ### Community member behavior
 
 Everyone must follow our code of conduct
-
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,3 +1,3 @@
 # FuseML Architecture
 
-TBD
+TBD
diff --git a/docs/cli.md b/docs/cli.md
@@ -160,14 +160,14 @@ services:
 
 To register the extension as a YAML file with the FuseML CLI:
 
-```
+```bash
 > fuseml extension register -f mymlflow.yaml
 Extension "mymlflow" successfully registered
 ```
 
 Alternatively, to build the same extension step by step:
 
-```
+```bash
 > fuseml extension register --id mymlflow -p mlflow --version 1.19.0 --zone dev-server --desc "MLFlow experiment tracking service"
 Extension "mymlflow" successfully registered
 
@@ -197,7 +197,7 @@ using a prediction service.
 
 Getting a workflow to execute is basically a two step process:
 
-- first, configure a workflow definition from a yaml or json file. Consult the [API Refefence](api.md) section for a
+- first, configure a workflow definition from a yaml or json file. Consult the [API Reference](api.md) section for a
   full description of the workflow format.
 - then, use the command line to assign a codeset to the workflow. The workflow is automatically triggered as a result of the
   assignment, as well as every time a new version of the assigned codeset is published. The status, as well as the results(s)
@@ -303,7 +303,7 @@ steps:
 
 To create a workflow from the YAML file with the FuseML CLI:
 
-```
+```bash
 > fuseml workflow create example.yaml
 Workflow "example" successfully created
 ```

diff --git a/docs/index.md b/docs/index.md
@@ -30,6 +30,7 @@ Well, it depends on what you would you like to do:
 ## Demo video
 
 No time for reading? Here's a sneak preview of the installation process of FuseML components.
+
 <div class="video-wrapper">
 <iframe width="760" height="515" src="https://www.youtube.com/embed/MAJhtJU8eCM?controls=0" title="FuseML Installation Experience" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 </div>
@@ -39,7 +40,7 @@ No time for reading? Here's a sneak preview of the installation process of FuseM
 The team behind FuseML is reachable through:
 
 - [Github](https://github.com/fuseml)
-- Slack channel: [Join](https://join.slack.com/t/fuseml/shared_invite/zt-rcs6kepe-rGrMzlj0hrRlalcahWzoWg)
+- [Slack](https://join.slack.com/t/fuseml/shared_invite/zt-rcs6kepe-rGrMzlj0hrRlalcahWzoWg)
 - [YouTube](https://www.youtube.com/channel/UCQLoLTikJDDMXvywWd27FBg)
 
 ## Sponsor FuseML

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -2,7 +2,7 @@
 
 In order to use FuseML one may simply do the following:
 
-### 1. Install the requirements
+## 1. Install Requirements
 
 We assume that a Kubernetes cluster is already up and running. If not a good way to start with a local cluster is to use [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/), [Rancher K3s](https://k3s.io/) or [k3d](https://k3d.io/).
 
@@ -16,7 +16,7 @@ Additional software requirements:
 
 - _kubectl_: install the package provided by your OS, or check [upstream installation guide](https://kubernetes.io/docs/tasks/tools/#kubectl)
 
-### 2. Download and install the fuseml-installer
+## 2. Get `fuseml-installer`
 
 ```bash
 # On Linux
@@ -26,13 +26,13 @@ curl -sfL https://raw.githubusercontent.com/fuseml/fuseml/main/install.sh | sh -
 You should get an output similar to this:
 
 ```bash
-********* SUCCESS **********
-FuseML Installer is ready!
-To start using it just run fuseml-installer --help and enjoy!
-****************************
+Verifying checksum... Done.
+Preparing to install fuseml-installer into /usr/local/bin
+fuseml-installer installed into /usr/local/bin/fuseml-installer
+Run 'fuseml-installer --help' to see what you can do with it.
 ```
 
-### 3. Fuseml Installer is ready to go so let's install the components on the cluster:
+## 3. Install FuseML
 
 ```bash
 fuseml-installer install
@@ -47,61 +47,63 @@ You should get an output similar to this:
 
 Configuration...
   🧭  system_domain:
-  🧭  extension_repository: https://raw.githubusercontent.com/fuseml/extensions/main/installer/
+  🧭  extensions_repository: https://raw.githubusercontent.com/fuseml/extensions/main/installer/
+  🧭  force_reinstall: false
 
 🚢 Deploying Istio.....
 ✔️  Istio deployed
-.
-✔️  Created system_domain: 172.18.0.2.nip.io
+✔️  Created system_domain: 172.18.0.3.nip.io
 
 🚢 Deploying Workloads...
 ✔️  Workloads deployed
 
-🚢 Deploying Gitea.................................
-✔️  Gitea deployed (http://gitea.172.18.0.2.nip.io).
+🚢 Deploying Gitea......................................................
+✔️  Gitea deployed (http://gitea.172.18.0.3.nip.io).
 
-🚢 Deploying Registry..........
+🚢 Deploying Registry...............
 ✔️  Registry deployed
 
-🚢 Deploying Tekton.............................................................................
-✔️  Tekton deployed (http://tekton.172.18.0.2.nip.io).
+🚢 Deploying Tekton................................................................................
+✔️  Tekton deployed (http://tekton.172.18.0.3.nip.io).
 
-🚢 Deploying Core...........
-✔️  FuseML core component deployed (http://fuseml-core.172.18.0.2.nip.io).
+🚢 Deploying Core..............
+✔️  FuseML core component deployed (http://fuseml-core.172.18.0.3.nip.io).
 
 🚢 Downloading command line client...
-🚢 FuseML command line client saved as /home/jsuchome/kubernetes/fuseml/fuseml.
+🚢 FuseML command line client saved as /Users/flaviosr/workspace/fuseml/fuseml.
 Copy it to the location within your PATH (e.g. /usr/local/bin).
 
 🚢 To use the FuseML CLI, you must point it to the FuseML server URL, e.g.:
 
-    export FUSEML_SERVER_URL=http://fuseml-core.172.18.0.2.nip.io
+    export FUSEML_SERVER_URL=http://fuseml-core.172.18.0.3.nip.io
 
 ✔️  FuseML installed.
-System domain: 172.18.0.2.nip.io
+System domain: 172.18.0.3.nip.io
 ```
 
-The FuseML installer prints out URLs for _gitea_, _tekton_ and _fuseml-core_ components. You can access those sub-services directly at any given time. The fuseml core URL is especially important, as you'll need that to use the FuseML CLI.
+The FuseML installer prints out URLs for _gitea_, _tekton_ and _fuseml-core_ components. You can access those sub-services directly at any given time. The fuseml-core URL is especially important, as you'll need that to use the FuseML CLI.
 
 You can also see that the installer downloaded _fuseml_ command line client which you will use for actual FuseML operations. You can use the latest version which was downloaded automatically or manually choose one of [released versions](https://github.com/fuseml/fuseml-core/releases) from github.
 
-Use
+Run the following command to see the list of available commands:
 
 ```bash
 fuseml-installer install --help
 ```
 
-to get full information about the options the installer provides.
-
-### 4. Check if the components are up and running:
+## 4. Ensure FuseML components are up and running
 
 ```bash
-# Let's check the fuseml-core component
-kubectl get pods -n fuseml-core -o wide
-# Now let's check gitea
+# Check Istio
+kubectl get pods -n istio-system -o wide
+# Check Gitea
 kubectl get pods -n gitea -o wide
-# Let's check tekton
+# Check registry
+kubectl get pods -n fuseml-registry -o wide
+# Check tekton
 kubectl get pods -n tekton-pipelines -o wide
+# Check fuseml-core
+kubectl get pods -n fuseml-core -o wide
 ```
 
 If everything is in running or completed status, you are good to go. Continue on to the [tutorial](tutorials/kserve-basic.md) section and start to have fun with FuseML.