docs: add faq docs

Author: Col0ring

.changeset/tender-maps-kiss.md

@@ -0,0 +1,5 @@
+---
+'modelscope_studio': patch
+---
+
+docs: add FAQ docs

README-zh_CN.md

@@ -29,6 +29,8 @@
 
 然而，当您的应用需要 Gradio 在 Python 端更多地处理内置数据时，`modelscope_studio`的组件可能不是最好的选择，但是不用担心，它可以很好地与已有的 Gradio 组件相结合，您仍然可以使用`modelscope_studio`来优化您的应用。
 
+> 如果您正在 Hugging Face Space 中使用`modelscope_studio`，请在`demo.launch()`中添加`ssr_mode=False`参数：`demo.launch(ssr_mode=False)`，否则页面可能无法正常显示。
+
 ## 依赖
 
 - Gradio >= 4.43.0

README.md

@@ -29,6 +29,8 @@ Compared to the original components of Gradio, `modelscope_studio` focuses more
 
 However, when your application needs Gradio to handle more built-in data on the Python side, the components of `modelscope_studio` may not be the best choice, but don't worry, it integrates well with existing Gradio components, you can still use `modelscope_studio` to optimize your application.
 
+> If you are using `modelscope_studio` in Hugging Face Space, please add the `ssr_mode=False` parameter to the `demo.launch()`: `demo.launch(ssr_mode=False)`, otherwise the page may not display properly.
+
 ## Dependencies
 
 - Gradio >= 4.43.0

docs/FAQ-zh_CN.md

@@ -0,0 +1,19 @@
+# FAQ
+
+## 为什么我的应用在本地可以正常运行，在 Hugging Face Space 中界面无法正常显示？
+
+在 Hugging Face Space 中，默认开启了 Gradio 的 ssr 模式，但是此功能目前还无法很好的兼容自定义组件，需要我们手动关闭。请在`demo.launch()`方法中添加`ssr_mode=False`参数：`demo.launch(ssr_mode=False)`。
+
+## 为什么我的应用每次操作都需要等待一小段时间才会有响应
+
+`modelscope_studio`将组件的加载反馈进行了单独抽离。由于 Gradio 的交互操作涉及到前后端通信，需要有一段加载中的等待时间，当没有`AutoLoading`组件时，页面将不会显示 Gradio 的加载状态。因此，建议您至少在全局使用一次`AutoLoading`组件，以显示兜底的加载反馈。
+
+```python
+import gradio as gr
+import modelscope_studio.components.antd as antd
+import modelscope_studio.components.base as ms
+
+with gr.Blocks() as demo:
+    with ms.Application(), antd.ConfigProvider(), ms.AutoLoading():
+        antd.Button()
+```

docs/FAQ.md

@@ -0,0 +1,19 @@
+# FAQ
+
+## Why does my application run normally locally but the interface doesn't display properly in Hugging Face Space?
+
+In Hugging Face Space, Gradio's SSR mode is enabled by default, but this feature currently doesn't work well with custom components and needs to be manually disabled. Please add the `ssr_mode=False` parameter to the `demo.launch()`: `demo.launch(ssr_mode=False)`.
+
+## Why does my application need to wait for a short time before responding to each operation?
+
+`modelscope_studio` has separately extracted the loading feedback for components. Since Gradio's interactive operations involve frontend-backend communication, there needs to be a loading wait time. When there is no `AutoLoading` component, the page will not display Gradio's loading status. Therefore, it is recommended that you use the `AutoLoading` component at least once globally to display fallback loading feedback.
+
+```python
+import gradio as gr
+import modelscope_studio.components.antd as antd
+import modelscope_studio.components.base as ms
+
+with gr.Blocks() as demo:
+    with ms.Application(), antd.ConfigProvider(), ms.AutoLoading():
+        antd.Button()
+```

docs/README-zh_CN.md

@@ -23,6 +23,8 @@
 
 然而，当您的应用需要 Gradio 在 Python 端更多地处理内置数据时，`modelscope_studio`的组件可能不是最好的选择，但是不用担心，它可以很好地与已有的 Gradio 组件相结合，您仍然可以使用`modelscope_studio`来优化您的应用。
 
+> 如果您正在 Hugging Face Space 中使用`modelscope_studio`，请在`demo.launch()`方法中添加`ssr_mode=False`参数：`demo.launch(ssr_mode=False)`，否则页面可能无法正常显示。
+
 ## 依赖
 
 - Gradio >= 4.43.0

docs/README.md

@@ -40,6 +40,8 @@ Compared to the original components of Gradio, `modelscope_studio` focuses more
 
 However, when your application needs Gradio to handle more built-in data on the Python side, the components of `modelscope_studio` may not be the best choice, but don't worry, it integrates well with existing Gradio components, you can still use `modelscope_studio` to optimize your application.
 
+> If you are using `modelscope_studio` in Hugging Face Space, please add the `ssr_mode=False` parameter to the `demo.launch()`: `demo.launch(ssr_mode=False)`, otherwise the page may not display properly.
+
 ## Dependencies
 
 - Gradio >= 4.43.0

docs/app.py

@@ -62,7 +62,26 @@ def get_layout_templates():
 
 layout_templates = get_layout_templates()
 
-index_docs = {"overview": Docs(__file__), **layout_templates}
+misc_docs = Docs(__file__)
+
+
+class IndexDocsItem:
+
+    def __init__(self, module_name):
+        self.module_name = module_name
+
+    def get_css(self):
+        return misc_docs.get_css()
+
+    def render(self):
+        return misc_docs.render(module_name=self.module_name)
+
+
+index_docs = {
+    "overview": IndexDocsItem("README"),
+    "faq": IndexDocsItem("FAQ"),
+    **layout_templates
+}
 
 base_docs = get_docs("base")
 antd_docs = get_docs("antd")
@@ -73,6 +92,9 @@ def get_layout_templates():
 index_menu_items = [{
     "label": get_text("ModelScope-Studio", "ModelScope-Studio"),
     "key": "overview"
+}, {
+    "label": get_text("FAQ", "FAQ"),
+    "key": "faq"
 }, {
     "label":
     get_text("Layout Templates", "布局模板"),

docs/demos/example.py

@@ -7,4 +7,4 @@
         antd.DatePicker()
 
 if __name__ == "__main__":
-    demo.queue().launch()
+    demo.queue().launch(ssr_mode=False)

docs/helper/Docs.py

@@ -30,6 +30,11 @@ def __init__(self, file_path: str):
                 filter(lambda x: not x.endswith("-zh_CN.md"),
                        self.markdown_files))
 
+    def _get_filename(self, filename: str):
+        if is_modelscope_studio:
+            return f"{filename}-zh_CN.md"
+        return f"{filename}.md"
+
     def _remove_formatter(self, markdown_text):
         pattern = r"^ *---[\s\S]*?---"
         replaced_text = re.sub(pattern, "", markdown_text)
@@ -163,7 +168,10 @@ def get_css(self):
                 css += module.css
         return css
 
-    def render(self):
+    def render(self, module_name: str = None):
+        parsed_filename = self._get_filename(
+            module_name) if module_name else None
         with gr.Blocks() as demo:
-            self._render_markdown(self.markdown_files[0])
+            self._render_markdown(
+                parsed_filename if parsed_filename else self.markdown_files[0])
         return demo