Add FAQ doc (#346)

* Add FAQ doc

README.md

@@ -7,10 +7,15 @@
 
 [![GraphScope CI](https://github.com/alibaba/GraphScope/workflows/GraphScope%20CI/badge.svg)](https://github.com/alibaba/GraphScope/actions?workflow=GraphScope+CI)
 [![Coverage](https://codecov.io/gh/alibaba/GraphScope/branch/main/graph/badge.svg)](https://codecov.io/gh/alibaba/GraphScope)
+[![Playground](https://shields.io/badge/JupyterLab-Try%20GraphScope%20Now!-F37626?logo=jupyter)](https://try.graphscope.app)
+[![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/graphscope)](https://artifacthub.io/packages/helm/graphscope/graphscope)
+
 [![Docs-en](https://shields.io/badge/Docs-English-blue?logo=Read%20The%20Docs)](https://graphscope.io/docs)
+[![FAQ-en](https://img.shields.io/badge/FAQ-English-lightgrey?logo=Read%20The%20Docs)](https://graphscope.io/docs/frequently_asked_questions.html)
 [![Docs-zh](https://shields.io/badge/Docs-%E4%B8%AD%E6%96%87-blue?logo=Read%20The%20Docs)](https://graphscope.io/docs/zh/)
+[![FAQ-zh](https://img.shields.io/badge/FAQ-%E4%B8%AD%E6%96%87-lightgrey?logo=Read%20The%20Docs)](https://graphscope.io/docs/zh/frequently_asked_questions.html)
 [![README-zh](https://shields.io/badge/README-%E4%B8%AD%E6%96%87-blue)](README-zh.md)
-[![Playground](https://shields.io/badge/JupyterLab-Try%20GraphScope%20Now!-F37626?logo=jupyter)](https://try.graphscope.app)
+[![LICENSE](https://img.shields.io/badge/license-Apache--2.0-yellowgreen)](https://github.com/alibaba/GraphScope/blob/main/LICENSE)
 
 GraphScope is a unified distributed graph computing platform that provides a one-stop environment for performing diverse graph operations on a cluster of computers through a user-friendly Python interface. GraphScope makes multi-staged processing of large-scale graph data on compute clusters simple by combining several important pieces of Alibaba technology: including [GRAPE](https://github.com/alibaba/libgrape-lite), [MaxGraph](interactive_engine/), and [Graph-Learn](https://github.com/alibaba/graph-learn) (GL) for analytics, interactive, and graph neural networks (GNN) computation, respectively, and the [vineyard](https://github.com/alibaba/libvineyard) store that offers efficient in-memory data transfers.
 

docs/frequently_asked_questions.rst

@@ -0,0 +1,64 @@
+Frequently Asked Questions
+==========================
+
+Below are some questions which are frequently by our end users. If the following sections still doesn’t answer your question, feel free to open an `open an issue <https://github.com/alibaba/GraphScope/issues/new/choose>`_ or `post it to discussions <https://github.com/alibaba/GraphScope/discussions>`_.
+
+*1. What are the minimum resources and system requirements required to run GraphScope?*
+
+    To use GraphScope Python interface, **Python >= 3.6** and **pip >= 19.0** is required.
+    GraphScope engine can be deployed in standalone mode or distributed mode. For standalone deployment, a physical machine with at least **4 cores CPU** and **8G memory** is required. GraphScope is tested and supported on the following systems:
+
+    - CentOS7+
+    - Ubuntu18+
+
+    For distributed depolyment, a cluster managed by Kubernetes is required. GraphScope has tested on
+    k8s **version >= v1.12.0+**.
+
+
+*2. Is Kubernetes an enssential to run GraphScope?*
+
+    No. GraphScope supports `build and run on local <https://graphscope.io/docs/deployment.html#deployment-on-local>`_ in a single machine. 
+    However, GraphScope depends on many third-party libraries and projects. To make our life easier, we suggest you build and run GraphScope on k8s with our provided dev-image and release-image. If you don't have a kubernetes cluster, you may use tools like `kind <https://kind.sigs.k8s.io/>`_ to setup a local cluster to use the images for trying graphscope.
+
+
+*3. How to debug or get detailed information when run GraphScope?*
+
+    By default, GraphScope is usually running in a silent mode following the convention of Python applications.
+    To enable verbose logging, turn on it by this:
+
+    .. code:: python
+       
+       graphscope.set_option(show_log=True)
+
+    If you are running GraphScope in k8s, you can use `kubectl describe/logs <https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands>`_ to check the log/status of the cluster. If the disk space is accessible(on local or via pods), you may also find logs in `/tmp/graphscope/runtime/logs`.
+
+
+*4. Why I find more pods than expected with command `kubectl get pod`?*
+
+    For the failed pods, you may need to delete them manually.
+    This case is observed when using GraphScope with helm. If users did not correctly set the `role` and `rolebinding`, the command `helm uninstall GraphScope` may not correctly recycle allocated resources. More details please refer to `Helm Support <https://artifacthub.io/packages/helm/graphscope/graphscope>`_.
+
+
+*5. Is GraphScope a graph database?*
+
+    No, GraphScope is not a graph database.  It cannot provide transactions on graph.
+    Instead, it provides an efficient "immutable" in-memory store for fast queries and analysis, and a persistent store(service) for updates on graphs. Both are scale very well - you can launch a larger session from your python notebook to handle a bigger graph or run a complex algorithm.
+
+
+*6. What's the compatibility of Gremlin in GraphScope?*
+
+    GraphScope supports most querying operators in Gremlin. You may check the compatibility in this `link <https://graphscope.io/docs/interactive_engine.html#unsupported-features>`_.
+
+
+*7. The system seems get stuck, what are the possible reasons?*
+
+    If GraphScope seems to get stuck, the possible cause might be:
+
+    - In the session launching stage, the most cases are waiting for pods ready. The time consuming may be caused by a poor network connection during pulling image, or caused by the resources cannot meet the need to launch a session.
+    - In the graph loading stage, it is time consuming to load and build a large graph.
+    - When running a user-defined or built-in analytical algorithm, it takes time to compile/distribute the algorithm over the loaded graph.
+
+
+*I do have many other questions...*
+
+    Please feel free to contact us. You may reach us by `submitting an issue(prefered) <https://github.com/alibaba/GraphScope/issues/new/choose>`_, ask questions in `Discussions <https://github.com/alibaba/GraphScope/discussions>`_, or drop a message in `Slack <http://slack.graphscope.io>`_ or `DingTalk <https://h5.dingtalk.com/circle/healthCheckin.html?dtaction=os&corpId=ding82073ee2a22b2f86748126f6422b5d02&109d1=d3892&cbdbhh=qwertyuiop>`_. We are happy to answer your questions responsively.

docs/index.rst

@@ -29,6 +29,7 @@ and the vineyard store that offers efficient in-memory data transfers.
    interactive_engine
    analytics_engine
    learning_engine
+   frequently_asked_questions
    developer_guide
 
 .. toctree::

docs/installation.rst

@@ -11,7 +11,7 @@ To run GraphScope on your local computer, the following dependencies or tools ar
 
 - Docker
 - Python 3.8 (with pip)
-- Local Kubernetes cluster set-up tool (e.g. [Kind](https://kind.sigs.k8s.io))
+- Local Kubernetes cluster set-up tool (e.g. `Kind <https://kind.sigs.k8s.io>`_)
 
 On Windows and macOS, you can follow the official guides to install them and enable Kubernetes in Docker.
 For Ubuntu/CentOS Linux distributions, we provide a script to install the above

docs/zh/frequently_asked_questions.rst

@@ -0,0 +1,56 @@
+常见问题
+========
+
+我们收集了用户使用GraphScope过程中的常见问题，如果在下面的列表中仍然无法找到您遇到的问题的答案，可通过 `issue的方式 <https://github.com/alibaba/GraphScope/issues/new/choose>`_ 或 `在讨论区 <https://github.com/alibaba/GraphScope/discussions>`_ 与我们联系。
+
+
+*1. 运行GraphScope系统需要的最小资源是多少？*
+
+    在通过Python客户端使用GraphScope过程中，需要的最低Python版本是3.6+，最低pip版本是19.0+，GraphScope系统支持单机和分布式的方式部署，单机情况下，要求CPU至少4核，内存至少8G；
+    同时，GraphScope系统支持CentOS7+、Ubuntu18+、以及Kubernetes v1.12.0+
+
+
+*2. GraphScope是否强依赖Kubernetes?*
+
+    GraphScope不强依赖Kubernetes，同时也支持在 `本地环境环境下部署 <https://graphscope.io/docs/deployment.html#deployment-on-local>`_
+    然而，由于Graphscope依赖众多第三方的库和项目，为了节省你的时间，我们建议基于我们提供的镜像构建并运行GraphScope，如果你没有一个运行的Kubernetes集群，可以使用官方提供的 `kind <https://kind.sigs.k8s.io/>`_ 在本地快速搭建一个虚拟集群。
+
+
+*3. 如何如查看GraphScope的运行时信息？*
+
+    默认情况下，GraphScope运行不打印任何日志信息，你可以通过`show_log`参数开启日志输出。
+
+    .. code:: python
+       
+       graphscope.set_option(show_log=True)
+
+
+    如果您的GraphScope运行在k8s集群上，可以使用 `kubectl describe/logs <https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands>`_ 来查看系统的当前状态，同时如果你挂载可本地磁盘，也可在 `/tmp/graphscope/runtime/logs` 目录下查看运行时日志。
+
+
+*4. 为什么在使用 `kubectl get pod`命令时，发现了一些多余的pod?*
+
+    对于其中一些失败的pod，只能通过手动命令如 `kubectl delete pod <pod_name>` 进行删除。
+    通常情况下，该问题出现在使用Helm部署GraphScope时，目前，GraphScope依赖一些权限来删除运行时的资源，详细细节可以查看 `Helm Support <https://artifacthub.io/packages/helm/graphscope/graphscope>`_
+
+
+*5. GraphScope是图数据库吗？*
+
+    GraphScope并不是一个图数据库，其无法提供图上的一些事物性操作。GraphScope 将图分布式地载入内存作为不可变数据，来支持对该图的查询和分析操作。
+
+
+*6. GraphScope在Gremlin上的兼容性如何？*
+
+    目前，GraphScope支持Gremlin语言中的大部分查询算子，可通过 `该文档 <https://graphscope.io/docs/interactive_engine.html#unsupported-features>`_ 查看详细的支持信息。
+
+
+*7. GraphScope运行过程中常见的卡住原因*
+
+    - 在session拉起阶段，如果当前网络下载镜像过慢，或当前集群资源无法满足pod的拉起时，会造成一定的卡住现象。
+    - 载图阶段，可能会由于数据量过大造成短暂的卡住现象。
+    - 在执行图算法分析阶段，如果当前系统资源紧张，编译构建app时会花费一些时间。
+
+
+*8. 其他问题*
+
+    您可以通过 `issue的方式 <https://github.com/alibaba/GraphScope/issues/new/choose>`_ 或 `在讨论区 <https://github.com/alibaba/GraphScope/discussions>`_ 提出你的问题，同时，您也可以使用 `Slack <http://slack.graphscope.io>`_ 或 `DingTalk <https://h5.dingtalk.com/circle/healthCheckin.html?dtaction=os&corpId=ding82073ee2a22b2f86748126f6422b5d02&109d1=d3892&cbdbhh=qwertyuiop>`_ 与我们联系。

docs/zh/index.rst

@@ -39,6 +39,7 @@ GraphScope 的交互查询引擎的论文已被 NSDI 2021录用。
    interactive_engine
    analytics_engine
    learning_engine
+   frequently_asked_questions
    developer_guide
 
 .. toctree::

docs/zh/installation.rst

@@ -9,7 +9,7 @@ GraphScope 被设计为运行在 Kubernetes 管理的群集上。
 
 - Docker
 - Python 3.8 (with pip)
-- Local Kubernetes cluster set-up tool (e.g. [Kind](https://kind.sigs.k8s.io))
+- Local Kubernetes cluster set-up tool (e.g. `Kind <https://kind.sigs.k8s.io>`_)
 
 对于 Windows 和 MacOS 的用户，可通过官方文档来安装上述依赖, 并在Docker中开启Kubernetes功能。
 对于Ubuntu/CentOS Linux 发行版用户，我们提供了脚本来准备运行时环境。