bug(lint): fix markdown lint ci and refine docs markdown style (#702)

* fix markdown typo and unlimit the code block line length * fix docs style by markdownlint * update readme format
star-whale · Jul 4, 2022 · 5d91815 · 5d91815
1 parent 1780fa4
commit 5d91815
Show file tree

Hide file tree

Showing 14 changed files with 142 additions and 137 deletions.
diff --git a/README.md b/README.md
@@ -229,137 +229,144 @@ Let's go ahead and finish the tutorial on the on-premises instance.
 
 ![Create Job Workflow](docs/docs/img/create-job-workflow.gif)
 
-🍰 **STEP1**: installing minikube and helm
-
-- Minikube 1.25+
-- Helm 3.2.0+
-
-There are standard installation tutorials for [minikube](https://minikube.sigs.k8s.io/docs/start/) and [helm](https://helm.sh/docs/intro/install/) here.
-
-🍵 **STEP2**: Start minikube
-
-```bash
-minikube start
-alias kubectl="minikube kubectl --"
-```
-
-> For users in the mainland of China, please add these startup parameters：`--image-mirror-country='cn' --image-repository=registry.cn-hangzhou.aliyuncs.com/google_containers` for `minikube start`
-
-**Installation process**
-
-```bash
-helm repo add starwhale https://star-whale.github.io/charts
-helm repo update
-helm install my-starwhale starwhale/starwhale --version 0.2.0 -n starwhale --create-namespace --set minikube.enabled=true
-```
-
-After the installation is successful, the following prompt message appears:
-
-```bash
-NAME: my-starwhale
-LAST DEPLOYED: Thu Jun 23 14:48:02 2022
-NAMESPACE: starwhale
-STATUS: deployed
-REVISION: 1
-NOTES:
-******************************************
-Chart Name: starwhale
-Chart Version: 0.2.0
-App Version: 0.2.0
-...
-
-Port Forward Visist:
-  - starwhale controller:
-    - run: kubectl port-forward --namespace starwhale svc/my-starwhale-controller 8082:8082
-    - visit: http://localhost:8082
-  - minio admin:
-    - run: kubectl port-forward --namespace starwhale svc/my-starwhale-minio 9001:9001
-    - visit: http://localhost:9001
-  - mysql:
-    - run: kubectl port-forward --namespace starwhale svc/my-starwhale-mysql 3306:3306
-    - visit: mysql -h 127.0.0.1 -P 3306 -ustarwhale -pstarwhale
-
-******************************************
-Login Info:
-- starwhale: u:starwhale, p:abcd1234
-- minio admin: u:minioadmin, p:minioadmin
-
-*_* Enjoy using Starwhale. *_*
-```
-
-Then keep checking the minikube service status until all pods are running.
-
-```bash
-watch -n 1 kubectl get pods -n starwhale
-```
-
-| NAME | READY | STATUS | RESTARTS | AGE |
-|:-----|-------|--------|----------|-----|
-|my-starwhale-agent-cpu-64699|2/2|Running|0|1m
-|my-starwhale-controller-7d864558bc-vxvb8|1/1|Running|0|1m
-|my-starwhale-minio-7d45db75f6-7wq9b|1/1|Running|0|2m
-|my-starwhale-mysql-0|1/1|Running|0|2m
-
-Make the Starwhale controller accessible locally with the following command:
-
-```bash
-kubectl port-forward --namespace starwhale svc/my-starwhale-controller 8082:8082
-```
-
-☕ **STEP3**: Upload the artifacts to the cloud instance
-> **pre-prepared artifacts**
-> Before starting this tutorial, the following three artifacts should already exist on your machine：
->
-> - a starwhale model named mnist
-> - a starwhale dataset named mnist
-> - a starwhale runtime named pytorch-mnist
->
-> The above three artifacts are what we built on our machine using starwhale.
-
-1. Use swcli to operate the remote server
-    First, log in to the server:
+- 🍰 **STEP1**: Install minikube and helm
+
+  - Minikube 1.25+
+  - Helm 3.2.0+
+
+  There are standard installation tutorials for [minikube](https://minikube.sigs.k8s.io/docs/start/) and [helm](https://helm.sh/docs/intro/install/) here.
+
+- 🍵 **STEP2**: Start minikube
+
+    ```bash
+    minikube start
+    ```
+
+    > For users in the mainland of China, please add these startup parameters：`--image-mirror-country='cn' --image-repository=registry.cn-hangzhou.aliyuncs.com/google_containers` for `minikube start`
+
+    Installation process:
 
     ```bash
-    swcli instance login --username starwhale --password abcd1234 --alias server http://localhost:8082
+    helm repo add starwhale https://star-whale.github.io/charts
+    helm repo update
+    helm install my-starwhale starwhale/starwhale --version 0.2.0 -n starwhale --create-namespace --set minikube.enabled=true
     ```
 
-    Use the server instance as the default:
+    After the installation is successful, the following prompt message appears:
 
     ```bash
-    swcli instance select server
+    NAME: my-starwhale
+    LAST DEPLOYED: Thu Jun 23 14:48:02 2022
+    NAMESPACE: starwhale
+    STATUS: deployed
+    REVISION: 1
+    NOTES:
+    ******************************************
+    Chart Name: starwhale
+    Chart Version: 0.2.0
+    App Version: 0.2.0
+    ...
+
+    Port Forward Visit:
+    - starwhale controller:
+        - run: kubectl port-forward --namespace starwhale svc/my-starwhale-controller 8082:8082
+        - visit: http://localhost:8082
+    - minio admin:
+        - run: kubectl port-forward --namespace starwhale svc/my-starwhale-minio 9001:9001
+        - visit: http://localhost:9001
+    - mysql:
+        - run: kubectl port-forward --namespace starwhale svc/my-starwhale-mysql 3306:3306
+        - visit: mysql -h 127.0.0.1 -P 3306 -ustarwhale -pstarwhale
+
+    ******************************************
+    Login Info:
+    - starwhale: u:starwhale, p:abcd1234
+    - minio admin: u:minioadmin, p:minioadmin
+
+    *_* Enjoy using Starwhale. *_*
     ```
 
-2. Create a project named 'project_for_mnist' and make it default:
+    Then keep checking the minikube service status until all pods are running.
 
     ```bash
-    swcli project create project_for_mnist
-    swcli project select project_for_mnist
+    kubectl get pods -n starwhale
     ```
 
-3. Start copying the model, dataset, and runtime that we constructed earlier:
+    | NAME | READY | STATUS | RESTARTS | AGE |
+    |:-----|-------|--------|----------|-----|
+    |my-starwhale-agent-cpu-64699|2/2|Running|0|1m
+    |my-starwhale-controller-7d864558bc-vxvb8|1/1|Running|0|1m
+    |my-starwhale-minio-7d45db75f6-7wq9b|1/1|Running|0|2m
+    |my-starwhale-mysql-0|1/1|Running|0|2m
+
+    Make the Starwhale controller accessible locally with the following command:
 
     ```bash
-    swcli model copy local/project/self/model/mnist/version/latest http://localhost:8082/
-    swcli dataset copy local/project/self/dataset/mnist/version/latest http://localhost:8082/
-    swcli runtime copy local/project/self/runtime/pytorch-mnist/version/latest http://localhost:8082/
+    kubectl port-forward --namespace starwhale svc/my-starwhale-controller 8082:8082
     ```
 
-🍞 **STEP4**: Use the web UI to run an evaluation
+- ☕ **STEP3**: Upload the artifacts to the cloud instance
+
+    > **pre-prepared artifacts**
+    > Before starting this tutorial, the following three artifacts should already exist on your machine：
+    >
+    > - a starwhale model named mnist
+    > - a starwhale dataset named mnist
+    > - a starwhale runtime named pytorch-mnist
+    >
+    > The above three artifacts are what we built on our machine using starwhale.
+
+    1. Use swcli to operate the remote server
+        First, log in to the server:
+
+        ```bash
+        swcli instance login --username starwhale --password abcd1234 --alias server http://localhost:8082
+        ```
+
+        Use the server instance as the default:
+
+        ```bash
+        swcli instance select server
+        ```
+
+    2. Create a project named 'project_for_mnist' and make it default:
+
+        ```bash
+        swcli project create project_for_mnist
+        swcli project select project_for_mnist
+        ```
+
+    3. Start copying the model, dataset, and runtime that we constructed earlier:
+
+        ```bash
+        swcli model copy local/project/self/model/mnist/version/latest http://localhost:8082/
+        swcli dataset copy local/project/self/dataset/mnist/version/latest http://localhost:8082/
+        swcli runtime copy local/project/self/runtime/pytorch-mnist/version/latest http://localhost:8082/
+        ```
+
+- 🍞 **STEP4**: Use the web UI to run an evaluation
+
+    1. Log in Starwhale instance: let's use the username(starwhale) and password(abcd1234) to open the server web UI(<http://localhost:8082/>).
+    2. Then, we will see the project named 'project_for_mnist' that we created earlier with swcli. Click the project name, you will see the model, runtime, and dataset uploaded in the previous step.
+        <details>
+            <summary>Show the uploaded artifacts screenshots</summary>
 
-1. login
-Ok, let's use the username(starwhale) and password(abcd1234) to open the server web UI(<http://localhost:8082/>).
+        ![model list](docs/docs/img/ui-list-model.jpg)
+        ![dataset list](docs/docs/img/ui-list-dataset.jpg)
+        ![runtime list](docs/docs/img/ui-list-runtime.jpg)
+        </details>
+    3. Create an evaluation job
+        <details>
+            <summary>Show create job screenshot</summary>
 
-2. Then, we will see the project named 'project_for_mnist' that we created earlier with swcli.
-![project list](docs/docs/img/ui-list-project.jpg)
-Click the project name, you will see the model, runtime, and dataset uploaded in the previous step.
-![model list](docs/docs/img/ui-list-model.jpg)
-![dataset list](docs/docs/img/ui-list-dataset.jpg)
-![runtime list](docs/docs/img/ui-list-runtime.jpg)
-3. Create an evaluation job
-![Create job](docs/docs/img/ui-create-job.jpg)
+        ![Create job](docs/docs/img/ui-create-job.jpg)
+        </details>
+    4. The job is completed and the results can be viewed
+        <details>
+            <summary>Show the job evaluation result screenshot</summary>
 
-4. The job is completed and the results can be viewed
-![Show Job Results](docs/docs/img/ui-job-results.jpg)
+        ![Show Job Results](docs/docs/img/ui-job-results.jpg)
+        </details>
 
 **Congratulations! You have completed the evaluation process for a model.**
 

diff --git a/docs/.markdownlint.yaml b/docs/.markdownlint.yaml
@@ -68,7 +68,7 @@ MD013:
   # Number of characters for headings
   heading_line_length: 200
   # Number of characters for code blocks
-  code_block_line_length: 88
+  code_block_line_length: 1000
   # Include code blocks
   code_blocks: true
   # Include tables
@@ -153,9 +153,7 @@ MD031:
 MD032: true
 
 # MD033/no-inline-html - Inline HTML
-MD033:
-  # Allowed elements
-  allowed_elements: []
+MD033: false
 
 # MD034/no-bare-urls - Bare URL used
 MD034: true

diff --git a/docs/Makefile b/docs/Makefile
@@ -11,4 +11,4 @@ build-docs:
 	yarn build
 
 lint-docs:
-	markdownlint docs/*.md
+	markdownlint docs && markdownlint --disable=MD041 ../README.md
diff --git a/docs/docs/cloud/helm-charts.md b/docs/docs/cloud/helm-charts.md
@@ -48,7 +48,6 @@ helm delete starwhale
 |`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
 
 | Name | Description | Default Value|
@@ -90,4 +89,4 @@ helm upgrade --install starwhale starwhale/starwhale --namespace starwhale --cre
 
 - 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).
+- Your pull requests are always welcomed: [Github Repo](https://github.com/star-whale/starwhale).
diff --git a/docs/docs/quickstart/on-premises.md b/docs/docs/quickstart/on-premises.md
@@ -11,12 +11,16 @@ It is recommended to read [standalone quickstart](./standalone.md) first.
 Starwhale provides two ways to install an On-Premises instance in your private cluster:
 
 - For Kubernetes:
+
   - Standard Kubernetes Cluster: A pre-deployed Kubernetes cluster is required.
   - Minikube: You should have minikube and docker installed on your machine.
   - For more deployment details of Kubernetes, you can refer to this [doc](../cloud/helm-charts.md).
+
 - For Bare Metal: You should have these components installed: docker(>=19.03), nvidia-docker-plugin(optional). You can get more details from this [doc](../cloud/ansible.md).
 
-**In this tutorial, minikube is used instead of the standard Kubernetes cluster**
+:::notes
+In this tutorial, minikube is used instead of the standard Kubernetes cluster
+:::
 
 ### Prerequisites
 
@@ -147,7 +151,7 @@ swcli runtime copy local/project/self/runtime/pytorch-mnist/version/latest http:
 
 ### login
 
-Ok, let's use the username(starwhale) and password(abcd1234) to open the server web UI(<http://localhost:8082/>).
+Ok, let's use the username(starwhale) and password(abcd1234) to open the server [web UI](http://localhost:8082/).
 
 Then, we will see the project named 'project_for_mnist' that we created earlier with swcli.
 ![project list](../img/ui-list-project.jpg)
@@ -161,8 +165,6 @@ Click the project name, you will see the model, runtime, and dataset uploaded in
 ![Create job](../img/ui-create-job.jpg)
 ![Create Job Workflow](../img/create-job-workflow.gif)
 
-#### The job is completed and the results can be viewed
-
 ![Show Job Results](../img/ui-job-results.jpg)
 
 **Congratulations! You have completed the evaluation process for a model.**
diff --git a/docs/docs/quickstart/standalone.md b/docs/docs/quickstart/standalone.md
@@ -131,4 +131,4 @@ Run an evaluation job in the currently activated python runtime.
 The `job create` command will pull the runtime base image from ghcr.io by default. It may cost a lot of time for users in the mainland of China. `pip install` can be slow too.
 :::
 
-  👏 Now, you have completed the basic steps for Starwhale standalone.
+  👏 Now, you have completed the basic steps for Starwhale standalone.
diff --git a/docs/docs/reference/cli/instance.md b/docs/docs/reference/cli/instance.md
@@ -18,7 +18,6 @@ swcli instance [OPTIONS] COMMAND [ARGS]...
   - `[http(s)://]<hostname or ip>[:<port>]`: cloud instance with HTTP address.
   - `[cloud://]<cloud alias>`: cloud instance with an alias name, which can be configured in the instance login phase.
 
-
 ## All Sub-Commands
 
   |Command|Standalone|Cloud|

diff --git a/docs/docs/reference/cli/job.md b/docs/docs/reference/cli/job.md
@@ -125,7 +125,6 @@ swcli job list [OPTIONS]
     |`--page`||❌|Integer|1|Page number for jobs list|
     |`--size`||❌|Integer|20|Page size for jobs list|
 
-
 ## Remove a job
 
 ```bash

diff --git a/docs/docs/reference/cli/utilities.md b/docs/docs/reference/cli/utilities.md
@@ -43,4 +43,4 @@ swcli ui [INSTANCE]
     ```bash
     ❯ swcli ui  pre-k8s
     👏 try to open http://console.pre.intra.starwhale.ai
-    ```
+    ```
diff --git a/docs/docs/standalone/runtime.md b/docs/docs/standalone/runtime.md
@@ -60,4 +60,4 @@ starwhale_version: '0.2.0b20'
 ```
 
 - `swcli runtime create` command creates a `runtime.yaml` in the working dir, which is a RECOMMENDED method.
-- `swcli` uses `starwhale_version` version to render the docker image.
+- `swcli` uses `starwhale_version` version to render the docker image.
diff --git a/docs/docs/tutorials/ag_news.md b/docs/docs/tutorials/ag_news.md
@@ -42,7 +42,7 @@ $ source ~/code/starwhale/example/text_cls_AG_NEWS/venv/bin/activate
 
 ## Train the model
 
-> The training code in this repo is copied from https://pytorch.org/tutorials/beginner/text_sentiment_ngrams_tutorial.html. However, the dataset part is modified to understand better how Starwhale works.
+> The training code in this repo is copied from [Pytorch Tutorial](https://pytorch.org/tutorials/beginner/text_sentiment_ngrams_tutorial.html). However, the dataset part is modified to understand better how Starwhale works.
 
 ```console
 (pytorch_text) $ mkdir models

diff --git a/docs/docs/tutorials/cifar10.md b/docs/docs/tutorials/cifar10.md
@@ -27,7 +27,7 @@ pip install -r requirements.txt
 
 ## Train the model
 
-> The training code in this repo is sourced from https://pytorch.org/tutorials/beginner/blitz/cifar10_tutorial.html
+> The training code in this repo is sourced from [cifar10 tutorial](https://pytorch.org/tutorials/beginner/blitz/cifar10_tutorial.html).
 
 ```console
 mkdir models