fix access exceptions when rendering with sphinx

Signed-off-by: JoeyHwong <joeyhwong@gknow.cn>

README_zh.md

@@ -58,7 +58,10 @@ Sedna由以下组件构建：
 
 
 
-## 文档
+## 指南
+
+### 文档
+Sedna 在 [readthedoc.io](https://sedna.readthedocs.io/) 托管相关文档。 您可以根据这些文档更好地了解Sedna。
 ### 安装
 Sedna的安装文档请参考[这里](/docs/setup/install.md)。
 

docs/_static/css/custom.css

@@ -1,3 +1,7 @@
 .wy-nav-content{
     max-width: 100%;
-}
+}
+
+.rst-content .section img {
+	width: 1024px
+}

docs/conf.py

@@ -29,7 +29,6 @@ except ModuleNotFoundError:
     subprocess.check_call([sys.executable, "-m", "pip",
                            "install", "sphinx-autoapi"])
 
-
 _base_path = os.path.abspath('..')
 BASE_URL = 'https://github.com/kubeedge/sedna/'
 
@@ -53,7 +52,6 @@ for p in extra_paths:
     else:
         shutil.copy2(p, dst)
 
-
 with open(f'{_base_path}/lib/sedna/VERSION', "r", encoding="utf-8") as fh:
     __version__ = fh.read().strip()
 
@@ -140,30 +138,84 @@ extlinks = {
 }
 
 
-# hack to replace file link to html link
+# hack to replace file link to html link in markdown
 def ultimateReplace(app, docname, source):
-    path = app.env.doc2path(docname)
-    _match = re.compile("\(/([^/]+)/([^)]+)\)")
+    """
+    In the rendering with Sphinx, as some file links in markdown
+    can not be automatically redirected, and 404 response during
+    access, here define a regular to handle these links.
+    """
+    path = app.env.doc2path(docname)  # get current path
+
+    INLINE_LINK_RE = re.compile(r'\[[^\]]+\]\(([^)]+)\)')
+    FOOTNOTE_LINK_URL_RE = re.compile(r'\[[^\]]+\](?:\s+)?:(?:\s+)?(\S+)')
     if path.endswith('.md'):
         new_line = []
+
+        docs_url = os.path.join(_base_path, "docs")
         for line in source[0].split('\n'):
-            error_link = _match.search(line)
-            if error_link:
-                _path, _detail = error_link.groups()
-                if _path in ("docs", "examples") and ".md" in _detail.lower():
-                    tmp = os.path.join(_base_path, "docs")
-                    tmp2 = os.path.abspath(os.path.dirname(path))
-                    _relpath = os.path.relpath(tmp, tmp2).strip("/")
-                    line = line.replace("/docs/", f"{_relpath}/")
-                    line = line.replace("/examples/", f"{_relpath}/examples/")
-                else:
-                    line = line.replace(f"/{_path}/",
-                                        f"{BASE_URL}tree/main/{_path}/")
             line = re.sub(
-                "\((?!http)([^\)]+)\.md([^\)]+)?\)",
-                "(\g<1>.html\g<2>)", line
+                "\[`([^\]]+)`\]\[", "[\g<1>][", line
+            )  # fix html render error: [`title`]
+            replace_line = []
+            prev_start = 0
+            href_list = (
+                    list(INLINE_LINK_RE.finditer(line)) +
+                    list(FOOTNOTE_LINK_URL_RE.finditer(line))
             )
-            new_line.append(line)
+            for href in href_list:
+                pstart = href.start(1)
+                pstop = href.end(1)
+                if pstart == -1 or pstop == -1:
+                    continue
+                link = line[pstart: pstop]
+                if not link or link.startswith("http"):
+                    continue
+                if link.startswith("/"):
+                    tmp = _base_path
+                else:
+                    tmp = os.path.abspath(os.path.dirname(path))
+
+                _relpath = os.path.abspath(os.path.join(tmp, link.lstrip("/")))
+                for sp in extra_paths:  # these docs will move into `docs`
+                    sp = os.path.abspath(sp).rstrip("/")
+
+                    if not _relpath.startswith(sp):
+                        continue
+                    if os.path.isdir(sp):
+                        sp += "/"
+                    _relpath = os.path.join(
+                        docs_url, _relpath[len(_base_path):].lstrip("/")
+                    )
+                    break
+
+                if _relpath.startswith(docs_url) and (
+                        os.path.isdir(_relpath) or
+                        os.path.splitext(_relpath)[-1].lower().startswith(
+                            (
+                                    ".md", ".rst", ".txt", "html",
+                                    ".png", ".jpg", ".jpeg", ".svg", ".gif"
+                            )
+                        )
+                ):
+                    link = os.path.relpath(_relpath,
+                                           os.path.dirname(path))
+                    if not os.path.isdir(_relpath):  # suffix edit
+                        link = re.sub(
+                            "(?:\.md|\.rst|\.txt)(\W+\w+)?$",
+                            ".html\g<1>", link
+                        )
+                else:  # redirect to `github`
+                    _relpath = os.path.abspath(
+                        os.path.join(tmp, link.lstrip("/"))
+                    )
+                    _rel_root = os.path.relpath(_relpath, _base_path)
+                    link = f"{BASE_URL}tree/main/{_rel_root}"
+                p_line = f"{line[prev_start:pstart]}{link}"
+                prev_start = pstop
+                replace_line.append(p_line)
+            replace_line.append(line[prev_start:])
+            new_line.append("".join(replace_line))
         source[0] = "\n".join(new_line)
 
 

docs/index.rst

@@ -3,6 +3,7 @@ Sedna documentation
 ===========================================
 
 .. image:: ./_static/logo.png
+   :width: 200
 
 Sedna is an edge-cloud synergy AI project incubated in KubeEdge SIG AI. Benefiting from the edge-cloud synergy capabilities provided by KubeEdge, Sedna can implement across edge-cloud collaborative training and collaborative inference capabilities, such as joint inference, incremental learning, federated learning, and lifelong learning. Sedna supports popular AI frameworks, such as TensorFlow, Pytorch, PaddlePaddle, MindSpore.
 
@@ -36,8 +37,8 @@ Sedna can simply enable edge-cloud synergy capabilities to existing training and
     :glob:
     :caption: DEPLOY
 
-    setup/*
-
+    Installtion <setup/install>
+    Standalone <setup/local-up>
 
 .. toctree::
     :maxdepth: 1
@@ -48,7 +49,7 @@ Sedna can simply enable edge-cloud synergy capabilities to existing training and
     examples/incremental_learning/helmet_detection/README
     examples/joint_inference/helmet_detection_inference/README
     examples/lifelong_learning/atcii/README
-    examples/storage/s3/README
+    examples/storage/s3/*
 
 
 .. toctree::
@@ -61,12 +62,10 @@ Sedna can simply enable edge-cloud synergy capabilities to existing training and
     api/lib/*
 
 .. toctree::
-    :maxdepth: 1
     :caption: Contributing
-    :titlesonly:
-    :glob:
 
-    contributing/*
+    Prepare <contributing/prepare-environment>
+
 
 .. toctree::
     :maxdepth: 1
@@ -84,16 +83,6 @@ Sedna can simply enable edge-cloud synergy capabilities to existing training and
     roadmap
 
 
-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)
-
-
 RELATED LINKS
 =============
 

docs/proposals/dataset-and-model.md

@@ -73,7 +73,7 @@ The tables below summarize the group, kind and API version details for the CRDs.
 
 #### `Dataset` CRD
 
-[crd source](/build/crds/sedna/dataset_v1alpha1.yaml)
+[crd source](/build/crds/sedna.io_datasets.yaml)
 
 ```yaml
 apiVersion: apiextensions.k8s.io/v1
@@ -144,7 +144,7 @@ Current we support these below formats:
 
 #### `Model` CRD
 
-[crd source](/build/crds/sedna/model_v1alpha1.yaml)
+[crd source](/build/crds/sedna.io_models.yaml)
 ```yaml
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
@@ -209,7 +209,7 @@ spec:
 ### CRD type definition
 - `Dataset`
 
-[go source](cloud/pkg/apis/sedna/v1alpha1/dataset_types.go)
+[go source](/pkg/apis/sedna/v1alpha1/dataset_types.go)
 
 ```go
 package v1alpha1
@@ -259,7 +259,7 @@ type DatasetList struct {
 
 - `Model`
 
-[go source](cloud/pkg/apis/sedna/v1alpha1/model_types.go)
+[go source](/pkg/apis/sedna/v1alpha1/model_types.go)
 ```go
 package v1alpha1
 

docs/proposals/incremental-learning.md

@@ -74,7 +74,7 @@ The tables below summarize the group, kind and API version details for the CRD.
 |Kind                   | IncrementalLearningJob             |
 
 ### Incremental learning CRD
-See the [crd source](/build/crds/sedna/incrementallearningjob_v1alpha1.yaml) for details.
+See the [crd source](/build/crds/sedna.io_incrementallearningjobs.yaml) for details.
 
 ### Incremental learning job type definition
 

docs/proposals/joint-inference.md

@@ -64,7 +64,7 @@ The tables below summarize the group, kind and API version details for the CRD.
 
 ### Joint inference CRD
 
-see [crd source](/build/crd-samples/sedna/jointinferenceservice_v1alpha1.yaml)
+see [crd source](/build/crds/sedna.io_jointinferenceservices.yaml)
 
 ### Joint inference type definition
 

docs/quickstart.md

@@ -13,7 +13,7 @@ You can find the latest Sedna release [here](https://github.com/kubeedge/sedna/r
 
 ### Deploying Sedna
 
-Please refer to this [link](setup).
+Please refer to this [link](setup/install.md).
 
 ### Prepare
 

examples/storage/s3/README.md

@@ -3,7 +3,6 @@
 This example based on the example: [Using Incremental Learning Job in Helmet Detection Scenario](/examples/incremental_learning/helmet_detection/README.md)
 
 ### Create a secret with your S3 user credential.
-
 ```yaml
 apiVersion: v1
 kind: Secret
@@ -16,17 +15,15 @@ stringData: # use `stringData` for raw credential string or `data` for base64 en
   ACCESS_KEY_ID: XXXX
   SECRET_ACCESS_KEY: XXXXXXXX
 ```
-
+   
 ### Attach the created secret to the Model/Dataset/Job.
-`EDGE_NODE` and `CLOUD_NODE` are custom nodes, you can fill it which you actually run.  
-
+`EDGE_NODE` and `CLOUD_NODE` are custom nodes, you can fill it which you actually run.
 ```
 EDGE_NODE="edge-node" 
 CLOUD_NODE="cloud-node"
 ```
 
-* Attach the created secret to the Model.  
-
+* Attach the created secret to the Model.
 ```yaml
 kubectl create -f - <<EOF
 apiVersion: sedna.io/v1alpha1
@@ -53,8 +50,8 @@ spec:
 EO
 ```
 
-* Attach the created secret to the Dataset.  
-
+* Attach the created secret to the Dataset.
+    
 ```yaml
 kubectl $action -f - <<EOF
 apiVersion: sedna.io/v1alpha1
@@ -70,7 +67,6 @@ EOF
 
 ```
 * Attach the created secret to the Job(IncrementalLearningJob).
-
 ```yaml
 kubectl create -f - <<EOF
 apiVersion: sedna.io/v1alpha1
@@ -177,4 +173,4 @@ spec:
               type: Directory
   outputDir: "/incremental_learning/output"
 EOF
-```
+```