新增文档：如何写文档 (#729)

2026-09-24 23:12:34 +08:00 · 2018-09-17 23:14:49 +08:00
parent db06a01797
commit 464903988a
2 changed files with 83 additions and 3 deletions
@@ -12,9 +12,49 @@ We welcome all pull requests. Suggestions and feedback are also welcomed [here](

 1.  Add the script to the corresponding directory [/routes/](https://github.com/DIYgod/RSSHub/tree/master/routes)

-1.  Update [README (/en/README.md) ](https://github.com/DIYgod/RSSHub/blob/master/en/README.md) and [Documentation (/docs/en/README.md) ](https://github.com/DIYgod/RSSHub/blob/master/docs/en/README.md), preview the docs via `npm run docs:dev`
+1.  Update [Documentation (/docs/en/README.md) ](https://github.com/DIYgod/RSSHub/blob/master/docs/en/README.md), preview the docs via `npm run docs:dev`

-1.  Execute `npm run format` to lint the code before you commit and open a pull request
+    -   Documentation uses vue component:
+        -   `name`: route name
+        -   `author`: route authors, separated by a single space
+        -   `example`: route example
+        -   `path`: route path
+        -   `:paramsDesc`: route parameters description, in array, supports markdown
+            1. parameter description must be in the order of its appearance in route path
+            1. missing description will cause errors in `npm run docs:dev`
+            1. `'` `"` must be escaped as `\'` `\"`
+            1. it's redundant to indicate `optional/required` as the component will prepend based on `?`
+    -   Documentation examples:
+
+        -   Multiple parameters:
+
+        ```vue
+        <routeEn name="Issue" author="HenryQW" path="/github/issue/:user/:repo" example="/github/issue/DIYgod/RSSHub" :paramsDesc="['GitHub username', 'GitHub repo name']" />
+        ```
+
+        <routeEn name="Issue" author="HenryQW" path="/github/issue/:user/:repo" example="/github/issue/DIYgod/RSSHub" :paramsDesc="['GitHub username', 'GitHub repo name']" />
+
+        -   Use component slot for complicated description:
+
+        ```vue
+        <routeEn name="Flight Deals" author="HenryQW" path="/hopper/:lowestOnly/:from/:to?" example="/hopper/1/LHR/PEK" :paramsDesc="['set to `1` will return the cheapest deal only, instead of all deals, so you don\'t get spammed', 'origin airport IATA code', 'destination airport IATA code, if unset the destination will be set to `anywhere`']" >
+        
+        This route returns a list of flight deals (in most cases, 6 flight deals) for a period defined by Hopper's algorithm, which means the travel date will be totally random (could be tomorrow or 10 months from now).
+        
+        For airport IATA code please refer to [Wikipedia List of airports by IATA code](https://en.wikipedia.org/wiki/List_of_airports_by_IATA_code:_A)
+        
+        </routeEn>
+        ```
+
+        <routeEn name="Flight Deals" author="HenryQW" path="/hopper/:lowestOnly/:from/:to?" example="/hopper/1/LHR/PEK" :paramsDesc="['set to `1` will return the cheapest deal only, instead of all deals, so you don\'t get spammed', 'origin airport IATA code', 'destination airport IATA code, if unset the destination will be set to `anywhere`']" >
+
+        This route returns a list of flight deals (in most cases, 6 flight deals) for a period defined by Hopper's algorithm, which means the travel date will be totally random (could be tomorrow or 10 months from now).
+
+        For airport IATA code please refer to [Wikipedia List of airports by IATA code](https://en.wikipedia.org/wiki/List_of_airports_by_IATA_code:_A)
+
+        </routeEn>
+
+1)  Execute `npm run format` to lint the code before you commit and open a pull request

 ## Write the script

@@ -12,7 +12,47 @@ sidebar: auto

 1.  在 [/routes/](https://github.com/DIYgod/RSSHub/tree/master/routes) 中的路由对应路径添加获取 RSS 内容的脚本

-1.  更新 [README (/README.md) ](https://github.com/DIYgod/RSSHub/blob/master/README.md) 和 [文档 (/docs/README.md) ](https://github.com/DIYgod/RSSHub/blob/master/docs/README.md), 可以执行 `npm run docs:dev` 查看文档效果
+1.  更新 [文档 (/docs/README.md) ](https://github.com/DIYgod/RSSHub/blob/master/docs/README.md), 可以执行 `npm run docs:dev` 查看文档效果
+
+    -   文档采用 vue 组件形式, 格式如下:
+        -   `name`: 路由名称
+        -   `author`: 路由作者, 多位作者使用单个空格分隔
+        -   `example`: 路由举例
+        -   `path`: 路由路径
+        -   `:paramsDesc`: 路由参数说明, 数组, 支持 markdown
+            1. 参数说明必须对应其在路径中出现的顺序
+            1. 如缺少说明将会导致`npm run docs:dev`报错
+            1. 说明中的 `'` `"` 必须通过反斜杠转义 `\'` `\"`
+            1. 不必在说明中标注`可选/必选`, 组件根据`?`自动判断
+    -   文档样例:
+
+        -   多参数:
+
+        ```vue
+        <route name="仓库 Issue" author="HenryQW" example="/github/issue/DIYgod/RSSHub" path="/github/issue/:user/:repo" :paramsDesc="['用户名', '仓库名']"/>
+        ```
+
+          <route name="仓库 Issue" author="HenryQW" example="/github/issue/DIYgod/RSSHub" path="/github/issue/:user/:repo" :paramsDesc="['用户名', '仓库名']"/>
+
+        -   复杂说明支持 slot:
+
+        ```vue
+        <route name="分类" author="DIYgod" example="/juejin/category/frontend" path="/juejin/category/:category" :paramsDesc="['分类名']">
+        
+        | 前端     | Android | iOS | 后端    | 设计   | 产品    | 工具资源 | 阅读    | 人工智能 |
+        | -------- | ------- | --- | ------- | ------ | ------- | -------- | ------- | -------- |
+        | frontend | android | ios | backend | design | product | freebie  | article | ai       |
+        
+        </route>
+        ```
+
+          <route name="分类" author="DIYgod" example="/juejin/category/frontend" path="/juejin/category/:category" :paramsDesc="['分类名']">
+
+        | 前端     | Android | iOS | 后端    | 设计   | 产品    | 工具资源 | 阅读    | 人工智能 |
+        | -------- | ------- | --- | ------- | ------ | ------- | -------- | ------- | -------- |
+        | frontend | android | ios | backend | design | product | freebie  | article | ai       |
+
+          </route>

 1.  执行 `npm run format` 自动处理代码格式后, 提交代码, 然后提交 pull request