docs update: index and quickstart

Signed-off-by: Jie Pu <[email protected]>
kubeedge · Nov 12, 2021 · 1578174 · 1578174
1 parent cc08c26
commit 1578174
Show file tree

Hide file tree

Showing 11 changed files with 297 additions and 239 deletions.
diff --git a/docs/api/lib/index.rst b/docs/api/lib/index.rst
@@ -1,5 +1,5 @@
 ===========================================
-Sedna Python SDK
+Python API Use Guide
 ===========================================
 
 .. mdinclude:: ../../../lib/sedna/README.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,7 +58,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Sedna'
-copyright = '2020, Kubeedge'
+copyright = '2021, Kubeedge'
 author = 'Kubeedge'
 
 version = __version__

diff --git a/docs/index.rst b/docs/index.rst
@@ -9,21 +9,24 @@ Sedna is an edge-cloud synergy AI project incubated in KubeEdge SIG AI. Benefiti
 
 Sedna can simply enable edge-cloud synergy capabilities to existing training and inference scripts, bringing the benefits of reducing costs, improving model performance, and protecting data privacy.
 
+
 .. toctree::
     :maxdepth: 1
-    :titlesonly:
-    :glob:
-    :caption: DEPLOY
+    :caption: GUIDE
+
+    index/guide
+    index/quickstart
 
-    Cluster Installation <setup/install> used for production.
-    AllinOne Installation <setup/all-in-one> used for development.
-    Standalone Installation <setup/local-up> used for hello world.
 
 .. toctree::
     :maxdepth: 1
-    :caption: QUICK START
+    :titlesonly:
+    :glob:
+    :caption: DEPLOY
 
-    quickstart
+    Cluster Installation (for production) <setup/install>
+    AllinOne Installation (for development) <setup/all-in-one>
+    Standalone Installation (for hello world) <setup/local-up>
 
 
 .. toctree::
@@ -56,11 +59,13 @@ Sedna can simply enable edge-cloud synergy capabilities to existing training and
 
 .. toctree::
     :maxdepth: 1
-    :caption: API
+    :caption: API REFERENCE
     :titlesonly:
     :glob:
 
     api/lib/*
+    Python API <autoapi/lib/sedna/index>
+
 
 .. toctree::
     :maxdepth: 1
@@ -71,26 +76,17 @@ Sedna can simply enable edge-cloud synergy capabilities to existing training and
     Control Plane <contributing/prepare-environment>
 
 
-.. toctree::
-    :maxdepth: 1
-    :caption: API REFERENCE
-    :titlesonly:
-    :glob:
-
-    autoapi/lib/sedna/index
-
-
 .. toctree::
     :caption: ROADMAP
     :hidden:
 
-    roadmap
+    index/roadmap
 
 
 RELATED LINKS
 =============
 
-.. mdinclude:: related_link.md
+.. mdinclude:: index/related_link.md
 
 Indices and tables
 ==================

diff --git a/docs/index/guide.md b/docs/index/guide.md
@@ -0,0 +1,24 @@
+## Guide
+- If you are new to Sedna, you can try the command step by step in [quick start](./quickstart.md).
+- If you have played the above example, you can find more [examples](/examples/README.md).
+- If you want to know more about sedna's architecture and component, you can find them in [sedna home]. 
+- If you're looking to contribute documentation improvements, you'll specifically want to see the [kubernetes documentation style guide] before [filing an issue][file-an-issue].
+- If you're planning to contribute code changes, you'll want to read the [development preparation guide] next.
+- If you're planning to add a new synergy feature directly, you'll want to read the [guide][add-feature-guide] next.
+
+
+[proposals]: /docs/proposals
+[development preparation guide]: ../contributing/prepare-environment.md
+[add-feature-guide]: ../contributing/control-plane/add-a-new-synergy-feature.md
+
+[sedna home]: https://github.com/kubeedge/sedna
+[issues]: https://github.com/kubeedge/sedna/issues
+[file-an-issue]: https://github.com/kubeedge/sedna/issues/new/choose
+[file-a-fr]: https://github.com/kubeedge/sedna/issues/new?labels=kind%2Ffeature&template=enhancement.md
+
+[github]: https://github.com/
+[kubernetes documentation style guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md
+[recommended Git workflow]: https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md#workflow
+[pull request best practices]: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews
+[Kubernetes help wanted]: https://www.kubernetes.dev/docs/guide/help-wanted/
+
diff --git a/docs/setup/quick-start.md → docs/index/quick-start.md b/docs/setup/quick-start.md → docs/index/quick-start.md
diff --git a/docs/index/quickstart.md b/docs/index/quickstart.md
@@ -0,0 +1,183 @@
+
+# Quick Start
+
+
+The following is showing how to run a joint inference job by sedna.
+## Quick Start 
+
+#### 0. Check the Environment
+
+For Sedna all-in-one installation, it requires you:
+  - 1 VM **(one machine is OK, cluster is not required)**
+  - 2 CPUs or more
+  - 2GB+ free memory, depends on node number setting
+  - 10GB+ free disk space
+  - Internet connection(docker hub, github etc.)
+  - Linux platform, such as ubuntu/centos
+  - Docker 17.06+
+
+you can check the docker version by the following command, 
+```bash
+docker -v
+```
+after doing that, the output will be like this, that means your version fits the bill.
+```
+Docker version 19.03.6, build 369ce74a3c
+```
+
+
+#### 1. Deploy Sedna
+Sedna provides three deployment methods, which can be selected according to your actual situation:
+
+- [Install Sedna AllinOne](setup/all-in-one.md). (used for development, here we use it)
+- [Install Sedna local up](setup/local-up.md).  
+- [Install Sedna on a cluster](setup/install.md).
+
+The [all-in-one script](/scripts/installation/all-in-one.sh) is used to install Sedna along with a mini Kubernetes environment locally, including:
+  - A Kubernetes v1.21 cluster with multi worker nodes, default zero worker node.
+  - KubeEdge with multi edge nodes, default is latest KubeEdge and one edge node.
+  - Sedna, default is the latest version.
+
+  ```bash
+  curl https://raw.githubusercontent.com/kubeedge/sedna/master/scripts/installation/all-in-one.sh | NUM_EDGE_NODES=1 bash -
+  ```
+
+Then you get two nodes `sedna-mini-control-plane` and `sedna-mini-edge0`,you can get into each node by following command:
+
+```bash
+# get into cloud node
+docker exec -it sedna-mini-control-plane bash
+```
+
+```bash
+# get into edge node
+docker exec -it sedna-mini-edge0 bash
+```
+
+#### 1. Prepare Data and Model File
+
+* step1: download [little model](https://kubeedge.obs.cn-north-1.myhuaweicloud.com/examples/helmet-detection-inference/little-model.tar.gz) to your edge node.
+
+```
+mkdir -p /data/little-model
+cd /data/little-model
+wget https://kubeedge.obs.cn-north-1.myhuaweicloud.com/examples/helmet-detection-inference/little-model.tar.gz
+tar -zxvf little-model.tar.gz
+```
+
+* step2: download [big model](https://kubeedge.obs.cn-north-1.myhuaweicloud.com/examples/helmet-detection-inference/big-model.tar.gz) to your cloud node.
+
+```
+mkdir -p /data/big-model
+cd /data/big-model
+wget https://kubeedge.obs.cn-north-1.myhuaweicloud.com/examples/helmet-detection-inference/big-model.tar.gz
+tar -zxvf big-model.tar.gz
+```
+
+#### 2. Create Big Model Resource Object for Cloud
+On cloud node:
+```
+kubectl create -f - <<EOF
+apiVersion: sedna.io/v1alpha1
+kind:  Model
+metadata:
+  name: helmet-detection-inference-big-model
+  namespace: default
+spec:
+  url: "/data/big-model/yolov3_darknet.pb"
+  format: "pb"
+EOF
+```
+
+#### 3. Create Little Model Resource Object for Edge
+On cloud node:
+```
+kubectl create -f - <<EOF
+apiVersion: sedna.io/v1alpha1
+kind: Model
+metadata:
+  name: helmet-detection-inference-little-model
+  namespace: default
+spec:
+  url: "/data/little-model/yolov3_resnet18.pb"
+  format: "pb"
+EOF
+```
+
+#### 4. Create JointInferenceService 
+
+Note the setting of the following parameters, which have to same as the script [little_model.py](/examples/joint_inference/helmet_detection_inference/little_model/little_model.py):
+- hardExampleMining: set hard example algorithm from {IBT, CrossEntropy} for inferring in edge side.
+- video_url: set the url for video streaming. 
+- all_examples_inference_output: set your output path for the inference results.
+- hard_example_edge_inference_output: set your output path for results of inferring hard examples in edge side.
+- hard_example_cloud_inference_output: set your output path for results of inferring hard examples in cloud side.
+
+Make preparation in edge node
+```
+mkdir -p /joint_inference/output
+```
+
+Create joint inference service
+```
+CLOUD_NODE="sedna-mini-control-plane"
+EDGE_NODE="sedna-mini-edge0"
+
+kubectl create -f https://raw.githubusercontent.com/jaypume/sedna/main/examples/joint_inference/helmet_detection_inference/helmet_detection_inference.yaml 
+```
+
+
+#### 5. Check Joint Inference Status
+
+```
+kubectl get jointinferenceservices.sedna.io
+```
+
+#### 6. Mock Video Stream for Inference in Edge Side
+
+* step1: install the open source video streaming server [EasyDarwin](https://github.com/EasyDarwin/EasyDarwin/tree/dev).
+* step2: start EasyDarwin server.
+* step3: download [video](https://kubeedge.obs.cn-north-1.myhuaweicloud.com/examples/helmet-detection-inference/video.tar.gz).
+* step4: push a video stream to the url (e.g., `rtsp://localhost/video`) that the inference service can connect.
+
+```
+wget https://github.com/EasyDarwin/EasyDarwin/releases/download/v8.1.0/EasyDarwin-linux-8.1.0-1901141151.tar.gz
+tar -zxvf EasyDarwin-linux-8.1.0-1901141151.tar.gz
+cd EasyDarwin-linux-8.1.0-1901141151
+./start.sh
+
+mkdir -p /data/video
+cd /data/video
+wget https://kubeedge.obs.cn-north-1.myhuaweicloud.com/examples/helmet-detection-inference/video.tar.gz
+tar -zxvf video.tar.gz
+
+ffmpeg -re -i /data/video/video.mp4 -vcodec libx264 -f rtsp rtsp://localhost/video
+```
+
+### Check Inference Result
+
+You can check the inference results in the output path (e.g. `/joint_inference/output`) defined in the JointInferenceService config.
+* the result of edge inference vs the result of joint inference
+![](../../ /images/inference-result.png)
+![](../../examples/joint_inference/helmet_detection_inference/images/inference-result.png)
+
+## API
+
+- control-plane: Please refer to this [link](api/crd).
+- Lib: Please refer to this [link](api/lib).
+
+## Contributing
+
+Contributions are very welcome!
+
+- control-plane: Please refer to this [link](contributing/control-plane/development.md).
+- Lib: Please refer to this [link](contributing/lib/development.md).
+
+## Community
+
+Sedna is an open source project and in the spirit of openness and freedom, we welcome new contributors to join us. 
+You can get in touch with the community according to the ways:
+* [Github Issues](https://github.com/kubeedge/sedna/issues)
+* [Regular Community Meeting](https://zoom.us/j/4167237304)
+* [slack channel](https://app.slack.com/client/TDZ5TGXQW/C01EG84REVB/details)
+
diff --git a/docs/related_link.md → docs/index/related_link.md b/docs/related_link.md → docs/index/related_link.md
diff --git a/docs/roadmap.md → docs/index/roadmap.md b/docs/roadmap.md → docs/index/roadmap.md
@@ -4,18 +4,12 @@ This document defines a high level roadmap for sedna development.
 
 The [milestones defined in GitHub](https://github.com/kubeedge/sedna/milestones) represent the most up-to-date plans.
 
+## 2022 Roadmap
 
-## 2021 Q1 Roadmap
-
-- Support edge model and dataset management.
-- Support incremental learning, with time trigger, sample size trigger, and precision-based trigger, and integrating hard sample discovering algorithm.
-- Support collaborative training, integrating some common weight/gradient compression algorithm.  
-
-
-## Future
-
-- Integrate some common multi-task migration algorithms to resolve the problem of low precision caused by small size samples.
+- Integrate some common multi-task migration algorithms to resolve the problem of low precision caused by small size
+  samples.
 - Integrate KubeFlow and ONNX into Sedna, to enable interoperability of edge models with diverse formats.
-- Integrate typical AI frameworks into Sedna, include Tensorflow, Pytorch, PaddlePaddle and Mindspore etc. 
+- Integrate typical AI frameworks into Sedna, include Tensorflow, Pytorch, PaddlePaddle and Mindspore etc.
+- Support edge model and dataset management.