feat: refactoring + mermaid support & new-docs (#20)

* add exception domains + modified license desc Signed-off-by: Pratyay Banerjee <[email protected]> Signed-off-by: neilblaze <[email protected]> * feat: refactoring + mermaid support & new-docs Signed-off-by: neilblaze <[email protected]> * reorganized index-tree and purged UML images Signed-off-by: neilblaze <[email protected]> * minor updates Signed-off-by: neilblaze <[email protected]> * docs: change fork title Signed-off-by: frank-zsy <[email protected]> --------- Signed-off-by: Pratyay Banerjee <[email protected]> Signed-off-by: neilblaze <[email protected]> Signed-off-by: frank-zsy <[email protected]> Co-authored-by: frank-zsy <[email protected]>
X-lab2017 · May 24, 2024 · e199d67 · e199d67
1 parent 84542eb
commit e199d67
Show file tree

Hide file tree

Showing 10 changed files with 3,693 additions and 2,356 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -123,5 +123,8 @@ To ensure all your commits are signed, you may choose to add this alias to your
   commit = commit -s
 ```
 
+## Mermaid Diagrams
+If you are adding a new Mermaid diagram, you can use the [getting-started](https://mermaid.js.org/intro/getting-started.html) documentation to get started. You can also use the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) to create and preview your diagrams.
+
 ## Submitting
 Once you've committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. If you need to make any adjustments to your pull request, just push the updates to GitHub. Your pull request will automatically track the changes on your development branch and update.
diff --git a/docs/user_docs/metrics/openrank/community_openrank.md b/docs/user_docs/metrics/openrank/community_openrank.md
@@ -8,7 +8,30 @@
 
 与全域 OpenRank 指标的计算方法类似，该算法使用项目内的 Issue、PR 等协作数据来构建网络，其网络模型为：
 
-![Project OpenRank](https://www.plantuml.com/plantuml/png/SoWkIImgAStDuU8gpixCAqWiIinLI4bDIopDAN7BpolnIynDLN0CKWZmKGZrJinKSFRZuifDB51ukgVXQV_45msj2jLS2Wh-1QbvGObvsGgsTWhFfcvush27gnQYxidkoKztJIQWABEuk3ILW9g2qfoS-ABKmjBKuX8yIX7kij7LjOEQRANmRClk5zkRqMHHp4Ge0ki1Au2w7YZrTEEy9xlwk90rO5VXa9gN0WnD0000)
+<br/>
+
+```mermaid
+graph TD
+    classDef rounded rx:5,ry:5;
+    
+    Developer["开发者\n---------------------\nOpenRank | 数值"]:::rounded
+    issue["issue\n---------------------\nOpenRank | 数值"]:::rounded
+    pull_request["pull_request\n---------------------\nOpenRank | 数值"]:::rounded
+    repo["仓库\n---------------------\nOpenRank | 数值"]:::rounded
+
+    Developer -->|活跃| issue
+    Developer -->|活跃| pull_request
+    issue -->|属于| repo
+    pull_request -->|属于| repo
+```
+<!-- <br/> -->
+
+<!-- <details>
+<summary>Tap on **this** to view the high-res image of the UML diagram ▼</summary>
+<center><img src="https://www.plantuml.com/plantuml/png/SoWkIImgAStDuU8gpixCAqWiIinLI4bDIopDAN7BpolnIynDLN0CKWZmKGZrJinKSFRZuifDB51ukgVXQV_45msj2jLS2Wh-1QbvGObvsGgsTWhFfcvush27gnQYxidkoKztJIQWABEuk3ILW9g2qfoS-ABKmjBKuX8yIX7kij7LjOEQRANmRClk5zkRqMHHp4Ge0ki1Au2w7YZrTEEy9xlwk90rO5VXa9gN0WnD0000" alt="PlantUML" /></center>
+</details>
+
+<br/> -->
 
 ## 代码
 

diff --git a/docs/user_docs/metrics/openrank/global_openrank.md b/docs/user_docs/metrics/openrank/global_openrank.md
@@ -8,7 +8,24 @@
 
 全域 OpenRank 是`活跃度`指标的一个下游指标，借鉴了`活跃度`来构建 GitHub 全域项目与开发者之间的一个协作网络，其网络模型是：
 
-![OpenRankUML](https://www.plantuml.com/plantuml/png/SoWkIImgAStDuIhEpimhI2nAp5L8IKrBBCqfSSlFA_5Bp4rLS0nI2F1H2FLEp5HmzkFYoaqiK7Ywf-5f_yGN3QqArLmA2lu5gNb1YNdP2hPs2i-cRdZQi8Uh5gBkoUx9JtTDngC8OP2DhguTJBsLmhCjkrziR-PoICrB0JeE0000)
+
+```mermaid
+graph TD
+    classDef rounded rx:5,ry:5;
+    
+    Developer["开发者\n---------------------\nOpenRank | 数值"]:::rounded
+    repo["仓库\n---------------------\nOpenRank | 数值"]:::rounded
+
+    Developer --> |活跃| repo
+```
+<br/>
+
+<!-- <details>
+<summary>Tap on **this** to view the high-res image of the UML diagram ▼</summary>
+<center><img src="https://www.plantuml.com/plantuml/png/SoWkIImgAStDuIhEpimhI2nAp5L8IKrBBCqfSSlFA_5Bp4rLS0nI2F1H2FLEp5HmzkFYoaqiK7Ywf-5f_yGN3QqArLmA2lu5gNb1YNdP2hPs2i-cRdZQi8Uh5gBkoUx9JtTDngC8OP2DhguTJBsLmhCjkrziR-PoICrB0JeE0000" alt="OpenRankUML" /></center>
+</details>
+
+<br/> -->
 
 在全域 OpenRank 指标的实现中，使用`活跃度`指标作为开发者与仓库之间的边的权重，从而构建出全域协作网络来计算网络中每个节点在每个月的全域 OpenRank 值。但与`活跃度`不同的地方在于，我们并没有对开发者的加权活跃值进行开方运算，这是由于`活跃度`指标中的开方运算是为了将社区参与人数（社区规模）的因素引入到指标计算中，但对于协作网络而言，社区参与人数这个变量已经隐含在了网络结构中。
 

diff --git a/docs/user_docs/metrics/technical_fork.md b/docs/user_docs/metrics/technical_fork.md
@@ -0,0 +1,32 @@
+# Technical Fork (To be Translated)
+
+![Type](https://img.shields.io/badge/Type-Metric-blue) ![From](https://img.shields.io/badge/From-CHAOSS-blue) ![For](https://img.shields.io/badge/For-Repo-blue)
+
+## Definition
+
+Technical Fork is a metric defined by [CHAOSS](https://chaoss.community), see [CHAOSS Metrics - Technical Fork](https://chaoss.community/kb/metric-technical-fork/) for the detailed definition of this metric.
+
+A technical fork is a distributed version control copy of a project. The number of technical forks indicates the number of copies of a project on the same code development platform.
+
+> Fork from the same developer will be double counted. For example, if a developer has deleted the forked repository and then fork again, the latter fork will also be counted in the total.
+
+
+## Data
+
+**Link:** `https://oss.x-lab.info/open_digger/github/{owner}/{repo}/technical_fork.json`
+
+To get the data for a certain repository, replace `{owner}` and `{repo}` with the actual name. Here is an [example](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/technical_fork.json).
+
+## Code
+
+Here's the [**implementation code**](https://github.com/X-lab2017/open-digger/blob/465d2e3ddb57c0da7fab18435f711d4fa0a63f22/src/metrics/chaoss.ts#L12).
+
+
+
+## CodePen Demo
+
+<iframe height="600" scrolling="no" title="OpenDigger - [X-lab] Attention/Stars/Technical Fork/Bus Factor" src="https://codepen.io/frank-zsy/embed/MWBdpNg?type=technical_fork&default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/MWBdpNg?type=technical_fork">
+  OpenDigger - [X-lab] Attention/Stars/Technical Fork/Bus Factor</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -70,8 +70,14 @@ const config = {
         indexDocs: true,
       },
     ],
+    require.resolve("docusaurus-plugin-image-zoom"),
   ],
 
+  themes: ['@docusaurus/theme-mermaid'],
+  markdown: {
+    mermaid: true, 
+  },
+
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
@@ -112,6 +118,15 @@ const config = {
           },
         ],
       },
+      zoom: {
+        selector: '.markdown :not(em) > img',
+        config: {
+          background: {
+            light: 'rgb(255, 255, 255)',
+            dark: 'rgb(50, 50, 50)'
+          }
+        }
+      },
       footer: {
         style: 'dark',
         copyright: `Copyright © ${new Date().getFullYear()} X-lab<br>

diff --git a/i18n/en/docusaurus-plugin-content-docs/current/user_docs/metrics/technical_fork.md b/i18n/en/docusaurus-plugin-content-docs/current/user_docs/metrics/technical_fork.md
@@ -0,0 +1,32 @@
+# Technical Fork
+
+![Type](https://img.shields.io/badge/Type-Metric-blue) ![From](https://img.shields.io/badge/From-CHAOSS-blue) ![For](https://img.shields.io/badge/For-Repo-blue)
+
+## Definition
+
+Technical Fork is a metric defined by [CHAOSS](https://chaoss.community), see [CHAOSS Metrics - Technical Fork](https://chaoss.community/kb/metric-technical-fork/) for the detailed definition of this metric.
+
+A technical fork is a distributed version control copy of a project. The number of technical forks indicates the number of copies of a project on the same code development platform.
+
+> Fork from the same developer will be double counted. For example, if a developer has deleted the forked repository and then fork again, the latter fork will also be counted in the total.
+
+
+## Data
+
+**Link:** `https://oss.x-lab.info/open_digger/github/{owner}/{repo}/technical_fork.json`
+
+To get the data for a certain repository, replace `{owner}` and `{repo}` with the actual name. Here is an [example](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/technical_fork.json).
+
+## Code
+
+Here's the [**implementation code**](https://github.com/X-lab2017/open-digger/blob/465d2e3ddb57c0da7fab18435f711d4fa0a63f22/src/metrics/chaoss.ts#L12).
+
+
+
+## CodePen Demo
+
+<iframe height="600" scrolling="no" title="OpenDigger - [X-lab] Attention/Stars/Technical Fork/Bus Factor" src="https://codepen.io/frank-zsy/embed/MWBdpNg?type=technical_fork&default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/MWBdpNg?type=technical_fork">
+  OpenDigger - [X-lab] Attention/Stars/Technical Fork/Bus Factor</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>