docs: optimize docs and images (#107)

TuGraph-family · Jan 18, 2025 · 19378b0 · 19378b0
1 parent 6eb7635
commit 19378b0
Show file tree

Hide file tree

Showing 16 changed files with 81 additions and 40 deletions.
diff --git a/README-cn.md b/README-cn.md
@@ -18,6 +18,20 @@
 
 **[https://osgraph.com](https://osgraph.com)**
 
+
+## 快速开始
+
+当前OSGraph提供的默认6张基础开源图谱含义如下：
+
+| 图谱名称 | 图谱ID                   | 功能                                            |
+|----------|------------------------|-----------------------------------------------|
+| 项目贡献图谱 | `project-contribution` | 根据项目开发者研发活动信息（Issue、PR、Commit、CR等），找到项目核心贡献者。 |
+| 项目生态图谱 | `project-ecosystem`    | 提取项目间的开发活动、组织等关联信息，构建项目核心生态关系。                |
+| 项目社区图谱 | `project-community`    | 根据项目的开发活动、开发者组织等信息，提取项目核心开发者社区分布。             |
+| 开发活动图谱 | `developer-activity`   | 根据开发者研发活动信息（Issue、PR、Commit、CR等），找到参与的核心项目。   |
+| 开源伙伴图谱 | `os-partner`           | 找到开发者在开源社区中，与之协作紧密的其他开发者。                     |
+| 开源兴趣图谱 | `os-interest`          | 根据参与的项目主题、标签等信息，分析开发者技术领域与兴趣。                 |
+
 在这里你可以参考[图谱示例](docs/zh-CN/demo.md)进行产品体验。
 
 使用Markdown直接引用OSGraph图谱？试试：
@@ -28,9 +42,6 @@
 
 具体请参考：[OSGraph API设计规范](docs/zh-CN/api-reference.md)
 
-
-## 快速开始
-
 本地启动测试请参考：[快速开始](docs/zh-CN/quick-start.md)
 
 如果你希望定制自己专有的图谱，可以参考：[开发手册](docs/zh-CN/developer-manual.md)
@@ -52,7 +63,7 @@
 
 
 
-##  参与贡献
+## 参与贡献
 
 您可以参考[贡献手册](community/CONTRIBUTING.md)提交GitHub Issue/PR对OSGraph反馈建议与功能改进，也可以通过下面的联系方式加入TuGraph社区群与我们直接沟通交流。
 

diff --git a/README.md b/README.md
@@ -18,6 +18,19 @@
 
 **[https://osgraph.com](https://osgraph.com)**
 
+## QuickStart
+
+The following are the meanings of the 6 default basic open source graphs currently provided by OSGraph:
+
+| Graph Name | Graph ID | Function |
+|----------|------------------------|-----------------------------------------------|
+| Project Contribution Graph | `project-contribution` | Find core project contributors based on developer activity information (Issues, PRs, Commits, CRs, etc.). |
+| Project Ecosystem Graph | `project-ecosystem` | Extract relationships between projects' development activities and organizations to build core project ecosystem relationships. |
+| Project Community Graph | `project-community` | Extract core developer community distribution based on project development activities and developer organization information. |
+| Developer Activity Graph | `developer-activity` | Find core projects participated in based on developer activity information (Issues, PRs, Commits, CRs, etc.). |
+| Open Source Partner Graph | `os-partner` | Find other developers who collaborate closely with the developer in the open source community. |
+| Open Source Interest Graph | `os-interest` | Analyze developer's technical domains and interests based on participated project topics, tags and other information. |
+
 You can refer to [Graph Demo](docs/en-US/demo.md) for product experience.
 
 Want to directly embed OSGraph graphs in Markdown? Try:
@@ -28,8 +41,6 @@ Want to directly embed OSGraph graphs in Markdown? Try:
 
 For more details：[OSGraph API Reference](docs/en-US/api-reference.md)
 
-## QuickStart
-
 Startup and test on local machine: [Quick Start](docs/en-US/quick-start.md)
 
 Customize your own graph (DIY): [Developer Manual](docs/en-US/developer-manual.md)

diff --git a/docs/en-US/developer-manual.md b/docs/en-US/developer-manual.md
@@ -3,9 +3,18 @@
 ## 1. Introduction
 **OSGraph (Open Source Graph)** provides six open-source graph datasets for users to explore, including three project-related graphs (Contribution, Ecosystem, Community) and three development-related graphs (Activities, Partners, Interests). If these six graphs do not meet your needs, you can customize your own graphs following this document.
 
-## 2. Local Setup
 Refer to the [Quick Start](./quick-start.md) document to complete the local setup and testing of the OSGraph service.
 
+## 2. Product Design
+
+By writing GitHub Archive data into the [TuGraph](https://github.com/TuGraph-family) database, OSGraph builds a graph query service for open source, and uses [AntV](https://github.com/antvis) for graph visualization.
+
+![](../img/arch.jpg)
+
+Furthermore, by connecting different open source graphs, unlimited exploration and expansion of the open source graphs can be achieved.
+
+![](../img/expand.jpg)
+
 ## 3. Project Structure
 
 * Entry Point: `osgraph-service/server.py`
@@ -14,11 +23,11 @@ Refer to the [Quick Start](./quick-start.md) document to complete the local setu
 * Service Layer: `osgraph-service/app/services`
 * Data Layer: `osgraph-service/app/dal`
 
-## 4. Development Details
+## 4. Development
 
-### 4.1 Interface Layer Development
+### 4.1 Graph API Development
 
-#### 4.1.1 Interface Design Specifications
+#### 4.1.1 Graph API Design
 
 URLs in the interface layer follow standardized design principles, using consistent formats for RESTful APIs, shared pages, and shared images.
 
@@ -30,7 +39,7 @@ URLs in the interface layer follow standardized design principles, using consist
 
 For more details：[OSGraph API Reference](api-reference.md)
 
-#### 4.1.2 Adding New Graph Interfaces
+#### 4.1.2 Add Graph API
 
 Create a new graph interface in the `osgraph-service/app/routes` directory and call the corresponding manager for implementation.
 
@@ -53,7 +62,7 @@ class OSInterestController:
         ...
 ```
 
-### 4.2 Business Layer Development
+### 4.2 Graph Manager Development
 
 #### 4.2.1 Graph View Model
 
@@ -114,7 +123,7 @@ Meaning of edge models:
 | `CommonDevelop` | Development activities that users jointly participate in |
 | `ContributeRepo` | A user contributes to a repository                       |
 
-#### 4.2.2 Adding New Graph Managers
+#### 4.2.2 Add Graph Manager
 
 Create a manager in the `osgraph-service/app/managers` directory and call the respective service for implementation.
 
@@ -126,14 +135,14 @@ class OSInterestManager:
 ```
 
 
-### 4.3 Service Layer Development
+### 4.3 Graph Service Development
 
 
-#### 4.3.1 Adding New Graph Services
+#### 4.3.1 Add Graph Service
 
 Create a new service in the `osgraph-service/app/services/graph_services` directory.
 
-Configure the required service parameters. Use inputTypes to declare the main query type and filterKeys to define query parameters for the service.
+Configure the required service parameters. Use `inputTypes` to declare the main query type and `filterKeys` to define query parameters for the service.
 
 ```Python
 class OSInterestServiceConfig(ServiceConfig):
@@ -168,7 +177,7 @@ class OSInterestService(BaseService):
 ```
 
 
-### 4.4 Data Layer Development
+### 4.4 Graph Data Development
 
 #### 4.4.1 Graph Data Schema
 
@@ -178,12 +187,12 @@ The underlying graph schema for OSGraph is defined as follows:
 For details, you can visit the TuGraph console directly: [Link](http://127.0.0.1:7070/#/Workbench/CreateLabel)
 
 
-## 5. Development Example
+## 5. Development Demo
 
 ### 5.1 Requirement
-Build a "Development Language" graph to describe the programming languages a user prefers when contributing to open source.
+Build a "Development Language" graph (`dev-lang`) to describe the programming languages a user prefers when contributing to open source.
 
-### 5.2 Develop DevLangController
+### 5.2 Develop `DevLangController`
 
 ```python
 dev_lang_bp = Blueprint("dev_lang", __name__, url_prefix="/api/graphs")
@@ -203,7 +212,7 @@ def get_org_repo(platform, remaining_path):
     response = controller.get_graph(data)
 ```
 
-### 5.3 Develop DevLangManager
+### 5.3 Develop `DevLangManager`
 
 ```Python
 class DevLangManager:
@@ -231,9 +240,9 @@ class DevLangManager:
             return graph.to_dict()
 ```
 
-### 5.4 Develop DevLangService
+### 5.4 Develop `DevLangService`
 
-Configure the DevLangService service parameters.
+Configure the `DevLangService` service parameters.
 ```python
 class DevLangServiceConfig(ServiceConfig):
     def __init__(self):
@@ -247,7 +256,7 @@ class DevLangServiceConfig(ServiceConfig):
         )
 ```
 
-Implement the DevLangService service logic.
+Implement the `DevLangService` service logic.
 
 ```python
 class DevLangService(BaseService):
@@ -283,7 +292,7 @@ class DevLangService(BaseService):
             return results
 ```
 
-Register the DevLangService graph service.
+Register the `DevLangService` graph service.
 
 ```python
 SERVICE_CONFIGS = [
@@ -292,9 +301,9 @@ SERVICE_CONFIGS = [
 ]
 ```
 
-### 5.5 Validation
+### 5.5 Test
 
-Test the URL：http://127.0.0.1:8000/api/graphs/dev-lang/github/fanzhidongyzby?lang-limit=3
+Test URL：`http://127.0.0.1:8000/api/graphs/dev-lang/github/fanzhidongyzby?lang-limit=3`
 
 
 Response Result：

diff --git a/docs/img/arch.jpg b/docs/img/arch.jpg
diff --git a/docs/img/expand.jpg b/docs/img/expand.jpg
diff --git a/docs/img/fanzhidongyzby-part.png b/docs/img/fanzhidongyzby-part.png
diff --git a/docs/img/flink-comm.png b/docs/img/flink-comm.png
diff --git a/docs/img/graphs.png b/docs/img/graphs.png
diff --git a/docs/img/llama3-eco.png b/docs/img/llama3-eco.png
diff --git a/docs/img/osgraph-cn.jpg b/docs/img/osgraph-cn.jpg
diff --git a/docs/img/osgraph-en.jpg b/docs/img/osgraph-en.jpg
diff --git a/docs/img/sindresorhus-intr.png b/docs/img/sindresorhus-intr.png
diff --git a/docs/img/torvalds-act.png b/docs/img/torvalds-act.png
diff --git a/docs/img/torvalds-contrib.png b/docs/img/torvalds-contrib.png
diff --git a/docs/img/torvalds.png b/docs/img/torvalds.png
diff --git a/docs/zh-CN/developer-manual.md b/docs/zh-CN/developer-manual.md
@@ -3,8 +3,18 @@
 ## 1. 介绍
 **OSGraph (Open Source Graph)** 默认提供了6张开源数据图谱供大家体验，包含项目类图谱3个（贡献、生态、社区）、开发类3个（活动、伙伴、兴趣）。如果这6张图谱不能满足您的需求，您也可以根据此文档，定制属于您自己的图谱。
 
-## 2. 本地启动
-请选参考[快速开始](./quick-start.md)文档完成本地OSGraph服务启动测试。
+请先参考[快速开始](./quick-start.md)文档完成本地OSGraph服务启动测试。
+
+## 2. 产品设计
+
+通过将GitHub Archive数据写入到[TuGraph](https://github.com/TuGraph-family)数据库，OSGraph构建了开源图谱的查询服务，并使用[AntV](https://github.com/antvis)完成图谱可视化。
+
+![](../img/arch.jpg)
+
+更进一步地，通过连接不同的开源图谱，可以对开源图谱进行无限的探索与扩展。
+
+![](../img/expand.jpg)
+
 
 ## 3. 项目结构
 
@@ -133,7 +143,7 @@ class OSInterestManager:
 
 在`osgraph-service/app/services/graph_services`目录中创建对应服务。
 
-配置必要的服务参数，inputTypes声明图谱的查询主体类型，filterKeys声明图谱服务的查询参数。
+配置必要的服务参数，`inputTypes`声明图谱的查询主体类型，`filterKeys`声明图谱服务的查询参数。
 
 ```Python
 class OSInterestServiceConfig(ServiceConfig):
@@ -158,7 +168,7 @@ SERVICE_CONFIGS = [
 ]
 ```
 
-编写execute函数，并调用数据层`GraphClient`，获取所需的底图数据。
+编写`execute`函数，并调用数据层`GraphClient`，获取所需的底图数据。
 
 ```Python
 class OSInterestService(BaseService):
@@ -181,9 +191,9 @@ OSGraph底层图数据结构定义为：
 ## 5. 开发示例
 
 ### 5.1 需求
-构建一个“开发语言”图谱，描述用户开源贡献时偏爱的编程语言。
+构建一个“开发语言”图谱（`dev-lang`），描述用户开源贡献时偏爱的编程语言。
 
-### 5.2 开发DevLangController
+### 5.2 开发`DevLangController`
 
 ```python
 dev_lang_bp = Blueprint("dev_lang", __name__, url_prefix="/api/graphs")
@@ -203,7 +213,7 @@ def get_org_repo(platform, remaining_path):
     response = controller.get_graph(data)
 ```
 
-### 5.3 开发DevLangManager
+### 5.3 开发`DevLangManager`
 
 ```Python
 class DevLangManager:
@@ -231,9 +241,9 @@ class DevLangManager:
             return graph.to_dict()
 ```
 
-### 5.4 开发DevLangService
+### 5.4 开发`DevLangService`
 
-配置DevLangService服务参数。
+配置`DevLangService`服务参数。
 ```python
 class DevLangServiceConfig(ServiceConfig):
     def __init__(self):
@@ -248,7 +258,7 @@ class DevLangServiceConfig(ServiceConfig):
 ```
 
 
-实现DevLangService服务逻辑。
+实现`DevLangService`服务逻辑。
 
 ```python
 class DevLangService(BaseService):
@@ -284,7 +294,7 @@ class DevLangService(BaseService):
             return results
 ```
 
-注册DevLangService图谱服务。
+注册`DevLangService`图谱服务。
 
 ```python
 SERVICE_CONFIGS = [
@@ -293,9 +303,9 @@ SERVICE_CONFIGS = [
 ]
 ```
 
-### 5.5 验证
+### 5.5 测试
 
-访问测试URL：http://127.0.0.1:8000/api/graphs/dev-lang/github/fanzhidongyzby?lang-limit=3
+访问测试URL：`http://127.0.0.1:8000/api/graphs/dev-lang/github/fanzhidongyzby?lang-limit=3`
 
 响应结果：
 ```json