一种基于代码注释自动生成开发文档的方法及系统专利检索-命令行界面软件专利检索查询-专利查询网

一种基于代码注释自动生成开发文档的方法及系统

阅读：203发布：2020-05-08

专利汇可以提供一种基于代码注释自动生成开发文档的方法及系统专利检索，专利查询，专利分析的服务。并且本发明公开了一种基于代码注释自动生成开发文档的方法及系统，其特征在于，包括如下步骤：安装webpack和react-styleguidist用于构建项目；在webpack配置文件同级目录下新建并配置styleguide.config.js文件，对项目的组件进行分类，将需要对外暴露的组件放在views目录下，通过通配符 select\*获取.jsx文件；通过包裹文件从项目中引入公共样式和特殊样式，对antd组件库进行全局设置，集成redux数据；在package.json中配置脚本；在webpack配置中通过env环境变量来分别给不同的环境添加设定不同的接口地址，再通过代理来正常访问接口。达到可以通过组件的代码注释自动生成，为各种使用场景编写demo以及对应的说明，同时附上demo源码，可以修改源码，实时预览demo的效果。，下面是一种基于代码注释自动生成开发文档的方法及系统专利的具体信息内容。

权利要求

1.一种基于代码注释自动生成开发文档的方法，其特征在于，包括如下步骤：
步骤1：安装文档生成器，具体为安装webpack和react-styleguidist用于构建项目；
步骤2：配置相关配置文件，在webpack配置文件同级目录下新建并配置
styleguide.config.js文件，通过sections参数对项目的组件进行分类，将需要对外暴露的组件放在views目录下，views目录下的每一个文件只能暴露一个组件，通过通配符select\*获取.jsx文件；
步骤3：配置外层包裹文件，具体为通过包裹文件从项目中引入公共样式和特殊样式，对antd组件库进行全局设置，集成redux数据；
步骤4：配置发布脚本，具体为在package.json中配置脚本，所述配置脚本包括文档的开发环境和生产环境；对于向后端请求数据的组件，通过在package.json中添加env环境变量，在webpack配置中通过env环境变量来分别给不同的环境添加设定不同的接口地址，再通过代理来正常访问接口。
2.如权利要求1所述的一种基于代码注释自动生成开发文档的方法，其特征在于：所述步骤1中，react-styleguidist内部集成react-docgen、remark和react-simple-code-editor，所述react-docgen用于提取注释，所述remark用于获取markdown文件，所述react-simple-code-editor用于实时编辑代码。
3.如权利要求2所述的一种基于代码注释自动生成开发文档的方法，其特征在于：所述步骤2中，所述项目的组件的分类目录包括components目录和pages目录，对配置文件中getComponentPathLine方法进行设定，具体内容包括：通过path.basename方法处理组件路径获取文件名称，通过path.dirname方法获取组件文件夹路径，项目中引入组件为前三个层级的路径，通过slice和join方法保留路径的前三个层级，处理组件引入名称，如果文件名称为index，则import的组件名称用文件夹的名称，如果文件名称不为index，则import的组件名称为组件的文件名称，同时添加花括号。
4.如权利要求3所述的一种基于代码注释自动生成开发文档的方法，其特征在于：所述步骤3中，如果项目中用到redux，则添加一个wrapper.js包裹文件，然后在styleguide.config.js的styleguideComponents参数里面指定这个文件。
5.如权利要求4所述的一种基于代码注释自动生成开发文档的方法，其特征在于：所述步骤2中，组件一共分为四类，包括业务类组件、整体布局组件、通用类组件和下拉选择组件，所述下拉选择组件是在pages目录下，通过通配符select\*获取以select开头的.jsx文件；所述步骤4中，所述代理为nginx代理。
6.一种根据权利要求1-5之一所述方法运行的基于代码注释自动生成开发文档的系统，其特征在于：包括通过文档生成器相连的项目和组件库；
所述项目为前端react项目，包含项目中所有组件代码；
所述文档生成器为react-styleguidist，包括配置文件、注释提取模块和示例提取模块，所述配置文件包括styleguide.config.js，所述注释提取模块为react-docgen，用于从react组件中提取信息以生成文档的命令行界面和工具包，把代码提取成json格式的数据，所述示例提取模块是一种markdown文件的处理器，用于生成以及格式化markdown文件，所述文档生成器用于实现文档的提取和生成；
所述组件库为包含组件使用文档和示例的系统或平台。

说明书全文

一种基于代码注释自动生成开发文档的方法及系统

技术领域

[0001] 本发明涉及计算机处理技术的服务发现领域，特别是涉及一种基于代码注释自动生成开发文档的方法及系统。

背景技术

[0002] 开发一个React项目，我们需要开发很多React组件，特别是一些公共的组件，在开发完成一个组件之后我们会面临以下几个问题：

[0003] 项目组一位同事想使用该组件，但是不知道怎么使用，必须去找之前使用过该组件的页面，或者直接看组件源码，比较麻烦耗时，而且还不一定能搞明白；一位新加入项目组的同事想先熟悉下项目看看有哪里公共组件，如果这时候有一些demo示例就很直观了；甚至是开发组件自己的人过了很长时间再去使用该组件也会忘记每个参数方法是什么意思。

[0004] 最原始的方法莫过于我们自己新建一个平台，当我们在项目中开发完成组件后，然后在另外的文档系统写一些使用的文档和示例。但是这样做会浪费开发人员很多时间，此外比较重要的一点的是我们需要安排专门人员来维护这个组件文档系统，而且经常会出现文档的更新滞后甚至是停止的现象，这样文档系统就会失去意义。

[0005] 目前市面上类似的文档生成系统并不多，大概有以下几种：

[0006] 1、通过普通的markdown文档生成系统，只能满足书写文档的要求，可用性比较低。

[0007] 2、Redemo是腾讯前端团队开发的一套React组件文档系统，但是与本地项目结合有一定难度，而且使用文档缺乏。

[0008] 3、Bi Sheng这个是ant-design(阿里团队)自己写的一套文档生成器，使用文档比较少，而且理解困难，另外与本地项目的结合有一定难度。

发明内容

[0009] 本发明所要解决的技术问题是克服现有技术的不足，提供一种基于代码注释自动生成开发文档的方法及系统，通过react-styleguidist文档生成器，根据代码注释自动生成文档，把文档以及demo的编写与项目融合在一起，支持开发实时预览模式和生产模式，实现了组件的编写和文档生产的同步。本发明能够减少维护开发文档的成本，为开发人员提供开发指南，同时文档与项目环境的同步使得文档的可用性提升。

[0010] 为解决上述技术问题，本发明提供一种基于代码注释自动生成开发文档的方法，其特征在于，包括如下步骤：

[0011] 步骤1：安装文档生成器，具体为安装webpack和react-styleguidist用于构建项目；

[0012] 步骤2：配置相关配置文件，在webpack配置文件同级目录下新建并配置styleguide.config.js文件，通过sections参数对项目的组件进行分类，将需要对外暴露的组件放在views目录下，views目录下的每一个文件只能暴露一个组件，通过通配符select\*获取.jsx文件；

[0013] 步骤3：配置外层包裹文件，具体为通过包裹文件从项目中引入公共样式和特殊样式，对antd组件库进行全局设置，集成redux数据；

[0014] 步骤4：配置发布脚本，具体为在package.json中配置脚本，所述配置脚本包括文档的开发环境和生产环境；对于向后端请求数据的组件，通过在package.json中添加env环境变量，在webpack配置中通过env环境变量来分别给不同的环境添加设定不同的接口地址，再通过代理来正常访问接口。

[0015] 所述步骤1中，react-styleguidist内部集成react-docgen、remark和react-simple-code-editor，所述react-docgen用于提取注释，所述remark用于获取markdown文件，所述react-simple-code-editor用于实时编辑代码。

[0016] 所述步骤2中，所述项目的组件的分类目录包括components目录和pages目录，对配置文件中getComponentPathLine方法进行设定，具体内容包括：通过path.basename方法处理组件路径获取文件名称，通过path.dirname方法获取组件文件夹路径，项目中引入组件为前三个层级的路径，通过slice和join方法保留路径的前三个层级，处理组件引入名称，如果文件名称为index，则import的组件名称用文件夹的名称，如果文件名称不为index，则import的组件名称为组件的文件名称，同时添加花括号。

[0017] 所述步骤3中，如果项目中用到redux，则添加一个wrapper.js包裹文件，然后在styleguide.config.js的styleguideComponents参数里面指定这个文件。

[0018] 所述步骤2中，组件一共分为四类，包括业务类组件、整体布局组件、通用类组件和下拉选择组件，所述下拉选择组件是在pages目录下，通过通配符select\*获取以select开头的.jsx文件；所述步骤4中，所述代理为nginx代理。

[0019] 一种基于代码注释自动生成开发文档的系统，其特征在于：包括通过文档生成器相连的项目和组件库；

[0020] 所述项目为前端react项目，包含项目中所有组件代码；

[0021] 所述文档生成器为react-styleguidist，包括配置文件、注释提取模块和示例提取模块，所述配置文件包括styleguide.config.js，所述注释提取模块为react-docgen，用于从react组件中提取信息以生成文档的命令行界面和工具包，把代码提取成json格式的数据，所述示例提取模块是一种markdown文件的处理器，用于生成以及格式化markdown文件，所述文档生成器用于实现文档的提取和生成；

[0022] 所述组件库为包含组件使用文档和示例的系统或平台。

[0023] 本发明所达到的有益效果:

[0024] (1)本发明通过代码注释自动生成文档，实现了根据react组件的代码注释自动生成文档系统的功能，避免了专人单独去维护文档系统，降低了文档的维护成本，提升了维护文档的效率。

[0025] (2)本发明通过把组件文档和demo示例的编写融合在项目中，使得文档系统和项目代码同步，提升了文档的可用性、准确性，有利于统一维护，同时它有独立编译和发布的功能，不会影响正式环境的发布。

[0026] (3)通过配置文件即可以与自身的项目进行结合，构建一个文档管理系统。

[0027] (4)可以变向要求开发人员写代码注释，养成一个好的开发习惯。附图说明

[0028] 图1为本发明的示例性实施例的方法流程示意图；

[0029] 图2为本发明的示例性实施例的系统结构示意图。

具体实施方式

[0030] 下面结合附图和示例性实施例对本发明作进一步的说明：

[0031] 如图1所示的一种基于代码注释自动生成开发文档的方法，包括如下步骤：

[0032] 步骤101：安装文档生成器。项目通过webpack进行构建，只需安装react-styleguidist即可，不需要其它繁琐的安装与环境配置。

[0033] 步骤102：配置相关配置文件。在webpack配置文件同级目录下新建并配置styleguide.config.js文件，有些特殊的配置方式需要根据项目的组件结构进行具体的配置，主要有下面两点：

[0034] (1)、组件获取部分配置代码如下：

[0035]

[0036] 上述配置用于告诉react-styleguidist需要获取项目中哪些组件以及组件如何分类等情况，包括组件库的前言部分，用于对组件库进行介绍；并对组件分成了四类进行提取，包括业务类组件、整体布局组件、通用类组件和下拉选择组件；项目中把需要对外暴露的组件放在views目录下面，通过通配符匹配模式进行匹配，如获取src/components/business/目录下面所有组件的views目录下面的.jsx文件；项目中有些下拉选择组件分布在src/pages目录下面，且其组件名称都是以select开头，我们通过通配符select\*获取以select开头的.jsx文件。

[0037] (2)、使用组件时需要引入组件，关键在于获取组件名称。

[0038] 组件引入的代码示例如下：

[0039] import Tooltip from'components/widgets/tooltip'；

[0040] import{Amount}from'components/business/amount'；

[0041] 因为有的组件下会暴露多个组件，且组件名称有的为index.jsx，有的为具体的名称，针对这种情况，我们对配置文件中getComponentPathLine方法进行了重写。

[0042] 代码如下：

[0043]

[0044]

[0045] 上述代码是对配置文件中getComponentPathLine方法进行设定，具体内容包括：先处理引入路径，通过path.basename方法处理组件路径获取文件名称，通过path.dirname方法获取组件文件夹路径，因为项目中引入组件为前三个层级的路径，所以通过slice和join方法来保留路径的前三个层级。再来处理组件引入名称，如果文件名称为index，则import的组件名称用文件夹的名称，如果文件名称不为index，则import的组件名称为组件的文件名称，同时添加花括号。

[0046] 步骤103：配置外层包裹文件。我们通过包裹文件来从项目中引入一些组件库需要用到的东西，这样可以实现项目和组件库资源共享，如果项目中用到redux，则添加一个wrapper.js包裹文件，然后在styleguide.config.js的styleguideComponents参数里面指定这个文件。

[0047] 代码如下：

[0048]

[0049]

[0050] 上图中的“import'styles/common.scss'；”为引入项目中的公共样式，如果组件库有单独的样式也在此处引入；“import'styles/ant.scss'；”处为对antd进行全局设置；“”处为集成redux数据。

[0051] 步骤104：配置发布脚本。在packages.json中配置开发环境和生产环境的脚本，但是由于项目中部分业务组件会向后端发起数据请求，所以会涉及到请求接口的问题。

[0052] 代码如下：

[0053] package.json代码：

[0054]

[0055]

[0056] 上述代码是package.json中的脚本，我们给不同环境设定了一个环境变量，然后在webpack的配置文件中通过这个环境变量来给不同环境设定不同接口地址，最后通过nginx代理实现正常访问接口。

[0057] 如图2所示的一种基于代码注释自动生成开发文档的系统，包括通过文档生成器相连的项目和组件库；

[0058] 所述项目为前端react项目，包含项目中所有组件代码；

[0059] 所述文档生成器为react-styleguidist，包括配置文件、注释提取模块和示例提取模块，所述配置文件包括styleguide.config.js，所述注释提取模块为react-docgen，用于从react组件中提取信息以生成文档的命令行界面和工具包，把代码提取成json格式的数据，所述示例提取模块是一种markdown文件的处理器，用于生成以及格式化markdown文件，所述文档生成器用于实现文档的提取和生成；

[0060] 所述组件库为包含组件使用文档和示例的系统或平台。

[0061] 本发明主要用于提供一种基于代码注释自动生成开发文档的方法及系统，其有益效果是：

[0062] (1)本发明通过代码注释自动生成文档，实现了根据react组件的代码注释自动生成文档系统的功能，避免了专人单独去维护文档系统，降低了文档的维护成本，提升了维护文档的效率。

[0063] (2)本发明通过把组件文档和demo示例的编写融合在项目中，使得文档系统和项目代码同步，提升了文档的可用性、准确性，有利于统一维护，同时它有独立编译和发布的功能，不会影响正式环境的发布。

[0064] (3)通过配置文件即可以与自身的项目进行结合，构建一个文档管理系统。

[0065] (4)可以变向要求开发人员写代码注释，养成一个好的开发习惯。

[0066] 以上实施例不以任何方式限定本发明，凡是对以上实施例以等效变换方式做出的其它改进与应用，都属于本发明的保护范围。

标题	发布/更新时间	阅读量
控制方法及电子设备	2020-05-19	824
一种安全指示信息的配置方法及设备	2020-05-12	233
一种用于计算热化学非平衡绕流的处理系统及方法	2020-05-13	148
一种数据实时处理系统及数据实时处理方法	2020-05-08	572
基于网络欺骗的网络防护方法、装置、设备及存储介质	2020-05-16	512
访问日志数据的统计方法、装置、计算机设备和存储介质	2020-05-13	597
设备定制信息的管理方法	2020-05-17	427
基于开源安全外壳协议的登录方法及登录系统	2020-05-19	461
WiFi ONU的自动化配置WAN的方法及应用	2020-05-12	941
网络设备的远程诊断方法及系统、网络设备及云服务器	2020-05-11	720

一种基于代码注释自动生成开发文档的方法及系统

一种基于代码注释自动生成开发文档的方法及系统

技术领域

背景技术

发明内容

具体实施方式

该功能需要专业版企业版VIP权限，您可以：