doc: upgrade docusaurus and fix doc typo (star-whale#1358)

upgrade docusaurus and fix doc typo
mfq1020 · Oct 14, 2022 · 0eb3ed3 · 0eb3ed3
1 parent 885546e
commit 0eb3ed3
Show file tree

Hide file tree

Showing 28 changed files with 2,296 additions and 1,022 deletions.
diff --git a/README.md b/README.md
@@ -400,7 +400,7 @@ Let's go ahead and finish the tutorial on the on-premises instance.
 
 ## Contributing
 
-🌼👏**PRs are always welcomed** 👍🍺.
+🌼👏**PRs are always welcomed** 👍🍺. See [Contribution to Starwhale](https://doc.starwhale.ai/docs/community/contribute) for more details.
 
 ## License
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -11,4 +11,4 @@ build-docs:
 	yarn build
 
 lint-docs:
-	markdownlint docs && markdownlint --disable=MD041 ../README.md
+	markdownlint docs i18n/zh  && markdownlint --disable=MD041 ../README.md
diff --git a/docs/docs/fundamentals/concepts.md b/docs/docs/fundamentals/concepts.md
@@ -4,21 +4,9 @@ title: Core Concepts
 
 This document explains the main concepts in Starwhale.
 
-```graph
-            Instance
-               |
-            Project
-               |
-   +-------+---+---+------+-------+
-   |       |       |      |       |
- Model  Dataset Runtime  Job  Evaluation
-   |       |       |      |       |
-Version Version Version  Step   Version
-  Tag     Tag    Tag      |
-                         Task
-```
-
-## Instance
+![concepts-org.jpg](../img/concepts-org.jpg)
+
+## 1. Instance
 
 Each installation of Starwhale is called an instance, Cloud or Standalone:
 
@@ -33,21 +21,21 @@ The on-premises instance and hosted instance are both called cloud instances. We
 
 **Starwhale tries to keep concepts consistent across different types of instances. In this way, people can easily exchange data and migrate between instances.**
 
-## Project
+## 2. Project
 
 Project is the basic unit for organizing different resources like models, datasets, etc.
 Users may use projects for different purposes. For example, we can create a project for a data scientist team, a product line, or a specific model. Users usually work on one or more projects in their daily lives.
 Every user in cloud instances has their personal project by default. Standalone instances also supports multi projects, `self` project will be created automatically and configured as the default project.
 
-## Model
+## 3. Model
 
 Starwhale Model is the standard model format used in model delivery.
 
 A Starwhale Model is a directory containing arbitrary files. It includes the model file generated by ML frameworks, the code file to run the model, the metadata file defined by Starwhale, and many other files.
 
 A Starwhale Model can contain any information required to run the model, such as source codes, different model formats, etc. It can be stripped of redundant information to get a smaller package. The primary purpose of a stripped Starwhale Model Package is for delivery. Users may not want to show python inference code to the production team for security reasons or need a minimum deployable package on edge.
 
-## Runtime
+## 4. Runtime
 
 Starwhale Runtime describes software dependencies to "run" a model. It includes python libraries, native libraries, native binaries, etc.
 
@@ -56,7 +44,7 @@ Stable software dependencies are essential for running a model. One reason is th
 Conda, Pip, and docker images are all solutions to define the software runtime environment. Starwhale Runtime supports all of them. Users can choose anyone they prefer.
 Starwhale provides the ability to synchronize runtimes on different machines and to switch between runtimes. Build once, use anywhere.
 
-## Dataset
+## 5. Dataset
 
 Starwhale organizes data into datasets.
 
@@ -66,7 +54,7 @@ Starwhale dataset provides a unified description of how the data and labels are
 
 Starwhale Dataset is just a collection of arbitrary data. It is up to the user how to define a dataset.
 
-## Version
+## 6. Version
 
 Starwhale manages the history of Model, Dataset, and Runtime. Every update appends a new version to the history.
 
@@ -76,12 +64,12 @@ Starwhale uses a linear history model. There is neither branch nor cycle in hist
 
 History can not be rollback. When a version is to be reverted, Starwhale copies the version and appends it to the end of the history. However, versions in the history can be manually removed and recovered.
 
-## Job, Step, and Task
+## 7. Job, Step, and Task
 
 A job is a set of programs to do specific work. A job consists of one or more steps, and each step consists of one or more tasks. Steps represent distinct stages of the work. They usually run with different codes. Tasks are replications of a step. Tasks in the same step always share the same program but run with separate data input.
 
 Starwhale uses jobs to execute actions like model training, evaluation, and serving.
 
-## Evaluation
+## 8. Evaluation
 
 **Starwhale Evaluation** manages the entire lifecycle of model evaluation which includes create job, distribute tasks and generate report etc.
diff --git a/docs/docs/guides/install/helm-charts.md b/docs/docs/guides/install/helm-charts.md
@@ -2,27 +2,27 @@
 title: Helm Charts Installation
 ---
 
-## Helm Charts
+## 1. Helm Charts
 
 Helm Charts helps you quickly deploy the whole Starwhale instance in Kubernetes.
 
 - To deploy, upgrade, and maintain the Starwhale `controller`.
 - To deploy third-party dependencies, such as minio, mysql, etc.
 
-## TL; DR
+## 2. TL; DR
 
 ```bash
 helm repo add starwhale https://star-whale.github.io/charts
 helm repo update
 helm install starwhale starwhale/starwhale -n starwhale --create-namespace
 ```
 
-## Prerequisites
+## 3. Prerequisites
 
 - Kubernetes 1.19+
 - Helm 3.2.0+
 
-## Installing the Chart
+## 4. Installing the Chart
 
 To install the chart with the release name starwhale:
 
@@ -31,24 +31,24 @@ helm repo add starwhale https://star-whale.github.io/charts
 helm install starwhale starwhale/starwhale
 ```
 
-## Uninstalling the Chart
+## 5. Uninstalling the Chart
 
 To remove the starwhale deployment:
 
 ```bash
 helm delete starwhale
 ```
 
-## Parameters
+## 6. Parameters
 
-### Common parameters
+### 6.1 Common parameters
 
 | Name             | Description                                                                                                                                                                                 | Default Value |
 |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
 | `image.registry` | image registry, you can find Starwhale docker images in docker.io or ghcr.io.                                                                                                               | `ghcr.io`     |
 | `image.org`      | image registry org, [starwhaleai](https://hub.docker.com/u/starwhaleai)(docker.io) or [star-whale](https://github.com/orgs/star-whale)(ghcr.io) or some custom org name in other registries | `star-whale`  |
 
-### Starwhale parameters
+### 6.2 Starwhale parameters
 
 | Name                        | Description                                | Default Value                    |
 |-----------------------------|--------------------------------------------|----------------------------------|
@@ -62,7 +62,7 @@ helm delete starwhale
 | `ingress.ingressClassName`  | ingress class name                         | `nginx`                          |
 | `ingress.host`              | starwhale controller domain                | `console.pre.intra.starwhale.ai` |
 
-### Infra parameters
+### 6.3 Infra parameters
 
 | Name                             | Description                                                                                                            | Default Value         |
 |----------------------------------|------------------------------------------------------------------------------------------------------------------------|-----------------------|
@@ -73,7 +73,7 @@ helm delete starwhale
 | `minio.persistence.storageClass` | minio pvc storageClass                                                                                                 | `local-storage-minio` |
 | `externalS3OSS.host`             | When minio.enabled is false, chart will use external s3 service.                                                       | `localhost`           |
 
-### minikube parameters
+### 6.4 minikube parameters
 
 | Name               | Description                            | Default Value |
 |--------------------|----------------------------------------|---------------|
@@ -85,8 +85,25 @@ In minikube mode, you can easy to build an all-in-one starwhale. Run command exa
 helm upgrade --install starwhale starwhale/starwhale --namespace starwhale --create-namespace --set minikube.enabled=true
 ```
 
-## Community
+### 6.5 dev mode
 
-- To report a bug or request a feature, use [Github Issues](https://github.com/star-whale/starwhale/issues/new/choose).
-- For online support, please join us on [Slack](https://join.slack.com/t/starwhale/shared_invite/zt-19b6cwnyo-BxMrZYWKj2J~kly1c32oEA).
-- Your pull requests are always welcomed: [Github Repo](https://github.com/star-whale/starwhale).
+| Name                        | Description                                              | Default Value    |
+|-----------------------------|----------------------------------------------------------|------------------|
+| `devMode.createPV.enabled`  | enable auto create PV                                    | `false`          |
+| `devMode.createPV.host`     | Node selector matchExpressions in kubernetes.io/hostname | ""               |
+| `devMode.createPV.rootPath` | Local path for test PV                                   | `/var/starwhale` |
+
+Dev mode support creating local path PV automatically when devMode.createPV.enabled sets to `true`
+
+e.g.
+
+```bash
+export SWNAME=starwhale
+export SWNS=starwhale
+helm install $SWNAME . -n $SWNS --create-namespace \
+    --set devMode.createPV.enabled=true \
+    --set devMode.createPV.host=pv-host \
+    --set devMode.createPV.rootPath=/path/to/pv-storage \
+    --set mysql.primary.persistence.storageClass=$SWNAME-mysql \
+    --set minio.persistence.storageClass=$SWNAME-minio
+```
diff --git a/docs/docs/guides/install/standalone.md b/docs/docs/guides/install/standalone.md
@@ -11,7 +11,7 @@ DO NOT install Starwhale in your system's global Python environment. It will cau
 
 We recommend you build an independent virutalenv or conda environment to install Starwhale.
 
-## Prerequisites
+## 1. Prerequisites
 
 - Python 3.7+
 - Linux or macOS
@@ -34,7 +34,7 @@ Starwhale works on macOS. If you run into issues with the default system Python3
 brew install python3
 ```
 
-## Install Starwhale with venv
+## 2. Install Starwhale with venv
 
 ```bash
 python3 -m venv ~/.cache/venv/starwhale
@@ -47,7 +47,7 @@ sudo rm -rf /usr/local/bin/swcli
 sudo ln -s `which swcli` /usr/local/bin/
 ```
 
-## Install Starwhale with conda
+## 3. Install Starwhale with conda
 
 ```bash
 conda create --name starwhale --yes  python=3.9
@@ -62,7 +62,7 @@ sudo ln -s `which swcli` /usr/local/bin/
 
 👏 Now, you can use `swcli` in the global environment.
 
-## Upgrade Starwhale
+## 4. Upgrade Starwhale
 
 ```bash
 #for venv
@@ -72,7 +72,7 @@ sudo ln -s `which swcli` /usr/local/bin/
 conda run -n starwhale python3 -m pip install --pre --upgrade starwhale
 ```
 
-## Remove Starwhale
+## 5. Remove Starwhale
 
 ```bash
 python3 -m pip remove starwhale

diff --git a/docs/docs/guides/uri.md b/docs/docs/guides/uri.md
@@ -6,21 +6,9 @@ title: Starwhale Resources URI
 **Resource URI is widely used in Starwhale client commands. The URI can refer to a resource in the local instance or any other resource in a remote instance. In this way, the Starwhale client can easily manipulate any resource.**
 :::
 
-```graph
-            Instance
-               |
-            Project
-               |
-   +-------+---+---+------+-------+
-   |       |       |      |       |
- Model  Dataset Runtime  Job  Evaluation
-   |       |       |      |       |
-Version Version Version  Step   Version
-  Tag     Tag    Tag      |
-                         Task
-```
+![concepts-org.jpg](../img/concepts-org.jpg)
 
-## Instance URI
+## 1. Instance URI
 
 Instance URI can be either:
 
@@ -43,7 +31,7 @@ swcli model copy mnist/version/latest cloud://pre-k8s/project/1
 swcli runtime copy pytorch/version/v1.0 http://localhost:8081/project/myproject
 ```
 
-## Project URI
+## 2. Project URI
 
 Project URI is in the format `[<Instance URI>/project/]<project name>`. If the instance URI is not specified, use the default instance instead.
 
@@ -54,7 +42,7 @@ swcli project select self   # select self project in the current instance
 swcli project info local/project/self  # inspect self project info in the local instance
 ```
 
-## Model/Dataset/Runtime URI
+## 3. Model/Dataset/Runtime URI
 
 - Model URI: `[<Project URI>/model/]<model name>[/version/<version id|tag>]`.
 - Dataset URI: `[<Project URI>/dataset/]<dataset name>[/version/<version id|tag>]`.
@@ -72,7 +60,7 @@ swcli model info mnist  # inspect mnist model info
 swcli job create --model mnist/version/latest --runtime pytorch-mnist/version/latest --dataset mnist/version/latest
 ```
 
-## Evaluation URI
+## 4. Evaluation URI
 
 - format: `[<Project URI>/evaluation/]<job id>`.
 - If the project URI is not specified, use the default project.
@@ -84,7 +72,7 @@ swcli eval info mezdayjzge3w   # Inspect mezdayjzge3w version in default instanc
 swcli eval info local/project/self/job/mezday # Inspect the local instance, self project, with short job version:mezday
 ```
 
-## Names Limitation
+## 5. Names Limitation
 
 Names mean project names, model names, dataset names, runtime names, and tag names.
 
@@ -93,7 +81,7 @@ Names mean project names, model names, dataset names, runtime names, and tag nam
 - A name should always start with a letter or the `_` character.
 - The maximum length of a name is 80.
 
-### Names uniqueness requirement
+### 5.1 Names uniqueness requirement
 
 The resource name should be a unique string within its owner. For example, the project name should be unique in the owner instance, and the model name should be unique in the owner project.
 

diff --git a/docs/docs/img/concepts-org.jpg b/docs/docs/img/concepts-org.jpg