From 9cb183361d4d15b5c7d35a218acb01fdcfa7b1c3 Mon Sep 17 00:00:00 2001 From: Rancho-7 <1027229497@qq.com> Date: Mon, 9 Oct 2023 22:22:32 +0800 Subject: [PATCH 1/6] test --- docs/index.html | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.html b/docs/index.html index 0708856..d925a8a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -76,6 +76,7 @@ } ) ] + } From 3503454031b723b17e902a14d6f1692920f2995b Mon Sep 17 00:00:00 2001 From: Rancho-7 <1027229497@qq.com> Date: Thu, 26 Oct 2023 09:39:25 +0000 Subject: [PATCH 2/6] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E9=94=99=E5=88=AB?= =?UTF-8?q?=E5=AD=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/zh-cn/faq.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md index 90a5441..ddd50fb 100644 --- a/docs/zh-cn/faq.md +++ b/docs/zh-cn/faq.md @@ -5,7 +5,7 @@ 如果你喜欢`smart-doc`，也请推荐给你的同事或者朋友，好的东西要分享给大家。 # smart-doc测试用例反馈 有些`bug`出现了，简单的`issue`中添加粘贴几行代码反馈的问题官方很难复现，这种情况下需要提供一个能够复现问题的代码。 -下面来说面下怎么给官方提供用例。 +下面来说下怎么给官方提供用例。 ## 单模块测试用例 如果你是单模块中就能复现的问题，则提用例的步骤如下： @@ -18,7 +18,7 @@ - 修改`fork`的代码添加测试用例，然后项目`gitee`上会有一个【Pull Request】的地方，选择给我们提pr即可，后面官方也会合并的测试用例进行问题的测试。 # 如何提升smart-doc生成文档的速度？ -`smart-doc maven`或者是`gradle`插件在默认请款下会自动分析项目的`pom`或者`gradle`提取依赖关系， +`smart-doc maven`或者是`gradle`插件在默认情况下会自动分析项目的`pom`或者`gradle`提取依赖关系， 然后自动去下载依赖的源码并加载到内存中，如果被加载的类越多，在完成源代码加载进入解析阶段就会需要执行扫描很多不必要的类 过滤。因此提升`smart-doc`生成文档速度最重要的就是让`smart-doc`的插件少加载代码。通常对于一个项目来说， 和生成文档`api`层直接关联的非常少，这些都是不必要的加载。 @@ -45,7 +45,7 @@ ```shell No plugin found for prefix 'smart-doc' in the current project and in the plugin groups [org.apache.maven.plugins, org.codehaus.mojo] available from the repositories ``` -这个问题其实和`smart-doc`没有任务关系，但是一些对`maven`不是很懂(只会简单使用)的同学会误认为是`smart-doc`的插件有问题。 +这个问题其实和`smart-doc`没有任何关系，但是一些对`maven`不是很懂(只会简单使用)的同学会误认为是`smart-doc`的插件有问题。 实际上这个是因为在项目中添加了`smart-doc`的`maven`插件后，自己的网络有些问题，导致并没有从`maven`仓库中下载到官方的插件。 # smart-doc和swagger的区别 尤其是新手，一定要了解`smart-doc`和`swagger`的本质区别： @@ -151,7 +151,7 @@ No plugin found for prefix 'smart-doc' in the current project and in the plugin - [Makefile参考](https://gitee.com/smart-doc-team/spring-boot-maven-multiple-module.git) -# 在多模块中构建使用smart-doc问什么会依赖报错？ +# 在多模块中构建使用smart-doc为什么会依赖报错？ `smart-doc`在这几年的发展中，随着使用的用户越来越多，时不时就会有同学问这个问题。 `Idea`这样的工具让开发编译打包`maven`或者`gradle`项目变得非常简单。但是也带来另外的问题， 那就是许多刚入行的开发者已经不知道怎么使用最基础的`mvn`命令来构建项目。 @@ -245,7 +245,7 @@ Yapi这些过去的开源产品，目前已经不怎么更新维护，也不像T # 为什么我的泛型嵌套对象无法分析啊？ -**遇到范型分析问题，请先升级到2.7.2+的版本。2.7.2开始后解析范型不再强行要求有源代码** +**遇到泛型分析问题，请先升级到2.7.2+的版本。2.7.2开始后解析泛型不再强行要求有源代码** 如果你有该疑问，那么你应该先思考下几点问题： @@ -295,13 +295,6 @@ public abstract class BaseResult
implements Serializable { "$ref":"..." ``` 如果出现上面格式的文本端，一般说明后台结构存在递归嵌套，这个标识自引用或者进入下一次重负递归。 -# 我是菜鸟能参与开源吗？ -开源软件最重要的指标并非是技术，社区的活跃度和代码贡献者数量才是衡量开源软件能够持续发展的指标。 -因此只要你有时间和愿意参与贡献，`smart-doc`的作者基本都指导你怎么去修改`issue`。 - -`smart-doc`的核心维护者中也有同学是从在校生开始加入开发，并在后面成功拿到国内某大厂`offer`的。 -因此我们非常欢迎愿意参与开源的同学加入，即便你是菜鸟都不用担心。 -`smart-doc`当前已经被国内许多一二线大厂所采用，未来只会更多。参与开源对菜鸟和萌新的帮助都是蛮大的。 # could not match input？ @@ -352,7 +345,7 @@ for(int i=0;i Date: Thu, 26 Oct 2023 12:05:29 +0000 Subject: [PATCH 3/6] add highlights to english dubbo doc --- docs/en/dubbo/dubbo.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/en/dubbo/dubbo.md b/docs/en/dubbo/dubbo.md index 8c67d83..301310d 100644 --- a/docs/en/dubbo/dubbo.md +++ b/docs/en/dubbo/dubbo.md @@ -1,15 +1,15 @@ ## Dubbo document generation -Smart-doc supports the generation of Apache Dubbo service interfaces documentation from version 1.8.7. The following describes how to use the smart-doc tool to generate dubbo's rpc internal interface documentation. +`Smart-doc` supports the generation of `Apache Dubbo Service API` documentation from version `1.8.7`. The following describes how to use the `smart-doc` tool to generate `Dubbo's RPC` internal interface documentation. ### Introduce -Smart-doc developed the maven plug-in and gradle based on the principle of simple use, through plug-ins to reduce the integration difficulty of smart-doc and remove the dependency intrusiveness. You can select the relevant plug-in according to the dependency build management tool you use. The following uses the smart-doc-maven-plugin plug-in to integrate smart-doc to generate dubbo as an example. Of course, you have two options for integrating smart-doc to generate dubbo rpc interface documentation: +`Smart-doc` developed the `maven` plug-in and `gradle` based on the principle of simple use, through plug-ins to reduce the integration difficulty of smart-doc and remove the dependency intrusiveness. You can select the relevant plug-in according to the dependency build management tool you use. The following uses the `smart-doc-maven-plugin` plug-in to integrate `smart-doc` to generate `Ddubbo` as an example. Of course, you have two options for integrating `smart-doc` to generate `Dubbo RPC` interface documentation: -- Use smart-doc to scan Dubbo service api module -- Use smart-doc to scan Dubbo provider module +- Use `smart-doc` to scan Dubbo service api module +- Use `smart-doc` to scan Dubbo provider module -Let's look at the integration method. +The integration method is as follows. #### Add plugin -Add smart-doc-maven-plugin to your dubbo service api or dubbo provider module. Of course you only need to select one method +Add `smart-doc-maven-plugin` to your `Dubbo Service API` or `Dubbo Provider` module. Of course you only need to select one method ```xml com.github.shalousun @@ -46,7 +46,7 @@ Add smart-doc-maven-plugin to your dubbo service api or dubbo provider module. O ``` #### Add configuration files required by smart-doc -Add the smart-doc.json configuration file to your dubbo service api or dubbo provider module resources. +Add the `smart-doc.json` configuration file to your `Dubbo Service API` or `Dubbo Provider` module resources. ```json { @@ -62,11 +62,11 @@ Add the smart-doc.json configuration file to your dubbo service api or dubbo pro "rpcConsumerConfig":"src/main/resources/consumer-example.conf"//Add dubbo consumer integration configuration to the document to facilitate the integration party to quickly integrate } ``` -About smart-doc, if you need more detailed configuration for generating documents, please refer to other documents on the official project wiki. +About `smart-doc`, if you need more detailed configuration for generating documents, please refer to other documents on the official project wiki. **rpcConsumerConfig：** -If you want to make dubbo consumer integration faster, you can put the integration configuration example in `consumer-example.conf`, and Smart-doc will output the example directly to the document. +If you want to make `Dubbo Consumer` integration faster, you can put the integration configuration example in `consumer-example.conf`, and smart-doc will output the example directly to the document. ``` dubbo: @@ -81,10 +81,10 @@ dubbo: ``` ### Apache Dubbo provider interface scan -As mentioned above, smart-doc supports scanning Apache Dubbo service api or dubbo provider separately. The scanning principle is mainly through the recognition of @dubbo annotation tags (idea can support adding custom annotation tags to remind you can refer to the smart-doc wiki document introduction) or dubbo's @service annotations. +As mentioned above, `smart-doc` supports scanning `Dubbo Service API` or `Dubbo Provider` separately. The scanning principle is mainly through the recognition of `@dubbo` annotation tags (idea can support adding custom annotation tags to remind you can refer to the `smart-doc` wiki document introduction) or `Dubbo's @service` annotations. #### Scan Apache Dubbo Service API -The dubbo service api is usually a very concise dubbo interface definition. If you need smart-doc to scan the dubbo interface, you need to add the @dubbo annotation tag. Examples are as follows: +The `Dubbo Service API` is usually a very concise `Dubbo` interface definition. If you need `smart-doc` to scan the `Dubbo` interface, you need to add the `@dubbo` annotation `tag``. Examples are as follows: ```java /** @@ -115,7 +115,7 @@ public interface UserService { ``` #### Scan Dubbo provider -If you want to generate rpc interface documentation through dubbo provider, you don't need to add any other annotation tags, smart-doc automatically scans @service annotations to complete. +If you want to generate `RPC` interface documentation through `Dubbo Provider`, you don't need to add any other annotation `tags`, `smart-doc` automatically scans `@service` annotations to complete. ```java /** @@ -156,7 +156,7 @@ public class UserServiceImpl implements UserService { ``` #### Generate operation -Run the plug-in's document generation command directly through the maven command or click the plug-in's visualization command directly in idea. +Run the plug-in's document generation command directly through the maven command `mvc` or click the plug-in's visualization command directly in `IDEA`. ![在这里插入图片描述](https://img-blog.csdnimg.cn/20200705230512435.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYWxvdXN1bg==,size_16,color_FFFFFF,t_70) -Run rpc-html etc. to generate dubbo rpc document +Run `rpc-html` etc. to generate `Dubbo RPC` document From 22e2fe029188ecf9b4afc2e1a22ed597de8fe47a Mon Sep 17 00:00:00 2001 From: Rancho-7 <1027229497@qq.com> Date: Fri, 27 Oct 2023 06:35:56 +0000 Subject: [PATCH 4/6] =?UTF-8?q?=E9=94=99=E5=88=AB=E5=AD=97=E8=B0=83?= =?UTF-8?q?=E6=95=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/zh-cn/plugins/maven_plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh-cn/plugins/maven_plugin.md b/docs/zh-cn/plugins/maven_plugin.md index aa022f6..405c1dd 100644 --- a/docs/zh-cn/plugins/maven_plugin.md +++ b/docs/zh-cn/plugins/maven_plugin.md @@ -110,7 +110,7 @@ smart-doc会自动分析依赖树加载所有依赖源码，不过这样会存 #### excludes & includes 最佳实践 1. 要使用include，加载需要的源码，如果不需要别的依赖，可以写项目自身的 `groupId:artifactId` -2. 遇到报错后，使用excludds排除报错依赖 +2. 遇到报错后，使用excludes排除报错依赖 ## 插件 executions From e64f6b8d6d8cd961ca1da066e061eda4eed7ae87 Mon Sep 17 00:00:00 2001 From: Rancho-7 <1027229497@qq.com> Date: Sun, 29 Oct 2023 17:57:52 +0800 Subject: [PATCH 5/6] =?UTF-8?q?=E6=B7=BB=E5=8A=A0maven=E6=8F=92=E4=BB=B6?= =?UTF-8?q?=E4=B8=AD=E8=AF=91=E8=8B=B1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/_sidebar.md | 4 + docs/en/plugins/maven-plugin-debug.md | 43 +++++ docs/en/plugins/maven_plugin.md | 227 +++++++++++++++++++++++ docs/zh-cn/_sidebar.md | 4 +- docs/zh-cn/plugins/gradle_plugin.md | 2 +- docs/zh-cn/plugins/maven-plugin-debug.md | 2 +- docs/zh-cn/plugins/maven_plugin.md | 4 +- 7 files changed, 280 insertions(+), 6 deletions(-) create mode 100644 docs/en/plugins/maven-plugin-debug.md create mode 100644 docs/en/plugins/maven_plugin.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 1d97963..93b5c4b 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -16,3 +16,7 @@ - [Document Effect](docsImages.md) - [Expand Development](expand.md) - [Changelog](changelog.md "Changelog") + +- Advanced Plugin Usage + - [maven插件使用进阶](en/plugins/maven_plugin.md "maven插件") + - [maven插件调试](en/plugins/maven-plugin-debug.md "maven插件调试") diff --git a/docs/en/plugins/maven-plugin-debug.md b/docs/en/plugins/maven-plugin-debug.md new file mode 100644 index 0000000..e472396 --- /dev/null +++ b/docs/en/plugins/maven-plugin-debug.md @@ -0,0 +1,43 @@ +When using the `smart-doc-maven-plugin` to build and generate `API` documentation, you may encounter some issues. + +If complex issues arise, only roughly summarizing error information in an `issue` report may not be sufficient for the official team to resolve the problem, as we cannot simulate the user's environment and their written code. + +Therefore, we hope that users of `smart-doc-maven-plugin` can obtain more detailed information by using `debug` when encountering errors. When submitting an `issue`, providing a detailed problem description can also help us resolve issues more quickly. + +The following will introduce how to debug the `smart-doc-maven-plugin` . + +# Add the smart-doc dependency +Because the `smart-doc-maven-plugin` ultimately utilizes `smart-doc` to perform the project's source code analysis and document generation, in most cases, the actual code debugging occurs in `smart-doc`. However, this process is primarily tracked through the `smart-doc-maven-plugin`. + +```xml + + com.github.shalousun + smart-doc + [Latest version] + test + +``` +**Note:** It's advisable to ensure that the version of `smart-doc` you use matches the version of `smart-doc` that the plugin depends on. + +# Add breakpoints +Add breakpoints as shown in the figure. + +![输入图片说明](../../_images/232807_f88b94b2_144669.png "maven-debug1.png") + +# Run the build target in Debug mode +Running the `maven` plugin in `debug` mode in `IDEA` is quite simple, as shown in the following figure. + +![启动debug](../../_images/233101_c48191e6_144669.png "maven-debug2.png") + +This way you can directly enter the breakpoints. + +**Tips:** The above method is for debugging the source code of `smart-doc` through the plugin as an entry point. If you want to debug the execution process of the plugin itself, add the plugin's dependency to the project's dependencies as follows: + +```xml + + com.github.shalousun + smart-doc-maven-plugin + 【Latest version】 + +``` +Then, follow similar steps to debug the source code of `smart-doc-maven-plugin`. \ No newline at end of file diff --git a/docs/en/plugins/maven_plugin.md b/docs/en/plugins/maven_plugin.md new file mode 100644 index 0000000..edd2bc2 --- /dev/null +++ b/docs/en/plugins/maven_plugin.md @@ -0,0 +1,227 @@ +The official `Maven` plugin is included from `smart-doc 1.7.9` onwards, allowing you to generate project documents directly by running the plugin. + +# Environment Requirements +- `Maven` 3.3.9+ +- `JDK`1.8+ + +# Plugin Usage Scope +In versions prior to `smart-doc-maven-plugin 1.0.2`, various issues existed when using the plugin in multi-module `Maven` projects. + +Starting from `smart-doc-maven-plugin 1.0.2`, we have put in a lot of effort into the plugin. This effort not only resolved various issues with the plugin in multi-module `Maven` projects but also enhanced `smart-doc` with greater source code loading capabilities. When using the plugin, `smart-doc's` document analysis capabilities have been significantly improved. + +`smart-doc-maven-plugin 1.0.8` added support for generating `Dubbo RPC` documentation. + +It's also recommended that users of older versions of `smart-doc-maven-plugin` upgrade to the latest version as soon as possible. In the future, when using `smart-doc`, it's recommended to use the plugin approach. + +> After using the plugin, you no longer need to add the `smart-doc` dependency to your project's `maven dependencies`. You can directly use the plugin. If you need to retain the original unit tests, you should include the `smart-doc` dependency. + +The usage reference is as follows: + +# Add the plugin + +```xml + + com.github.shalousun + smart-doc-maven-plugin + [Latest Version] + + ./src/main/resources/smart-doc.json + ${project.description} + + + com.baomidou:mybatis-plus-extension + + com.baomidou:mybatis-plus-core + + org.springframework.data:spring-data-commons + + + + + + compile + + + html + + + + +``` +## Plugin Configuration +### configFile +Specify the configuration file used for generating documentation. When using a relative path, please start with ./，eg: `./src/main/resources/smart-doc.json` + +### projectName +Specify the project name, it is recommended to use dynamic parameters, for example, ${project.description}. + +Starting from version 2.3.4, if projectName is not set in both the smart-doc.json and here, the plugin will automatically use the projectName from the pom file." + +### excludes & includes + +#### Source Code Loading Mechanism +Smart-doc automatically analyzes the dependency tree to load all source code. However, this approach presents two issues: + +1. Loading unnecessary source code, affecting documentation build efficiency. +2. When certain unnecessary dependencies are not loaded, it may result in errors (smart-doc, by default, assumes that all dependencies are required). + +#### Dependency Matching Rules +1. Match Single Dependency： `groupId:artifactId` +2. Regular Expression Matching for Multiple Dependencies： `groupId:.*` + + +#### includes +Use includes to selectively load dependencies and reduce unnecessary dependency parsing." + +Typically, the dependencies we need include a few common third-party libraries, internal company-owned libraries, and other modules within the project. + + +```xml + + + com.baomidou:mybatis-plus-extension + + com.baomidou:mybatis-plus-core + + org.springframework.data:spring-data-commons + + + + com.xxx:.* + +``` + + +#### excludes + +When encountering situations where certain classes cannot be loaded during plugin execution, exclude the dependencies associated with those classes. + +```xml + + + org.springframework.boot:spring-boot-mongodb + +``` + +#### excludes & includes Best Practices +1. Use `include` to load the necessary source code. If you don't need other dependencies, you can specify your project's own `groupId:artifactId`."） + +2. After encountering an error, use `excludes` to exclude the problematic dependencies. + + +## Plugin Executions + +### goal +Smart-doc provides goals such as html, openapi, markdown, and more. + + + + +# Add configuration for Smart-doc document generation +In the project, create a `smart-doc.json` configuration file. The plugin reads this configuration to generate the project's documentation. The content of this configuration is essentially the result of converting the `ApiConfig` previously written with unit tests into `json` format. Therefore, you can refer to the original unit test configuration for explanations of the configuration options. + +**Minimum Configuration Unit：** + +```properties +{ + "outPath": "D://md2" //Specify the output path for the documentation +} +``` + +For detailed configuration, please refer to the specific documentation (**Customization Configuration ** | **Configuration**). + +In the above `json` configuration example, only `"outPath"` is a required field. The rest of the configuration can be tailored to your project's specific requirements. + +**Note:** For existing users, it is entirely possible to convert `ApiConfig` into a `json` configuration using libraries like `Fastjson` or `Gson`. + +# Run the plugin to generate documentation +## 5.1 Using the Maven command line. +```bash +//Generate HTML +mvn -Dfile.encoding=UTF-8 smart-doc:html +//Generate Markdown. +mvn -Dfile.encoding=UTF-8 smart-doc:markdown +//Generate adoc. +mvn -Dfile.encoding=UTF-8 smart-doc:adoc +//Generate Postman json data. +mvn -Dfile.encoding=UTF-8 smart-doc:postman +// Generate Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5 +mvn -Dfile.encoding=UTF-8 smart-doc:openapi +// Generate documentation and push it to the Torna. +mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest + +// Apache Dubbo RPC document +// Generate html +mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html +// Generate markdown +mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown +// Generate adoc +mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc + +// Generate Dubbo documentation and push it to Torna. +mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc +``` +When building with the `mvn` command, if you want to view debug logs that can help analyze the source code loading process of the `smart-doc-maven` plugin, you can add the `-X` parameter. For instance: + +```bash +mvn -X -Dfile.encoding=UTF-8 smart-doc:html +``` + +**Note:** Especially on the `windows` system, if you encounter encoding issues when using the `mvn` command line for document generation, you may need to specify `-Dfile.encoding=UTF-8` when executing. + +Check the encoding for Maven. +```bash +# mvn -version +Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00) +Maven home: D:\ProgramFiles\maven\bin\.. +Java version: 1.8.0_191, vendor: Oracle Corporation +Java home: D:\ProgramFiles\Java\jdk1.8.0_191\jre +Default locale: zh_CN, platform encoding: GBK +OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos" +``` +## 5.2 Generate documentation in IntelliJ IDEA. +![idea中smart-doc-maven插件使用](../../_images/idea-maven-plugin.png "maven_plugin_tasks.png") + +# Plugin Project +[The source code for the smart-doc Maven plugin](https://gitee.com/smart-doc-team/smart-doc-maven-plugin) + +# Using the plugin in a multi-module Maven project + +When using `smart-doc` in a standalone Maven project, it's a smooth experience. However, in a multi-module Maven project with `smart-doc-maven-plugin`, you may have questions about where to place the `smart-doc` plugin. Should it be placed in the root `pom.xml` of Maven, or should it be placed in each module that needs to generate API documentation? + +Let's discuss where to place the plugin based on different project structures. + +For a fully parent-child relationship in a Maven project (if you are not sure what a fully parent-child relationship is, please search and learn): + +```xml +├─parent +├──common +│ pom.xml +├──web1 +│ pom.xml +├──web2 +│ pom.xml +└─pom.xml +``` +In the above Maven structure, it is assumed that it is strictly configured with parent-child relationships, and `web1` and `web2` both depend on `common`. In this situation, running the `mvn` command directly from within the `web1` or `web2` directories won't work. You need to run the build command from the root directory to successfully compile, as `smart-doc` plugin uses class loading to load user-configured classes, and it requires a build process similar to the execution command. + +In this scenario, it is recommended to place the `smart-doc-maven-plugin` in the root `pom.xml` and put the respective `smart-doc.json` configurations in `web1` and `web2`. + +Then use the `-pl` flag to specify which module `smart-doc` should generate documentation for. The command would look like this: + +``` +# Generate API documentation for the web1 module. +mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web1 -am +# Generate API documentation for the web2 module. +mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web2 -am +``` + +If the project doesn't strictly follow a parent-child structure, as in the example structure provided above, where the `common` module is placed within the `parent` but the `common` module's `pom.xml` does not define a parent. + +If the `common` module doesn't change frequently and many companies might upload the `common` module separately to their company's Nexus repository, in this scenario, `web1` and `web2` can each compile independently from their respective directories. In this case, you can place `smart-doc-maven-plugin` directly in `web1` and `web2` to build and generate documentation. + +[【Reference for multi-module test cases】](https://gitee.com/smart-doc-team/spring-boot-maven-multiple-module) + +**Note:** **There is no fixed pattern for using the plugin, the most important thing is to be proficient in the various `Maven` operations and adjust them according to your project's needs. With skill and familiarity, you'll be able to adapt easily.** + +**Regarding the plugin's usage, starting from `smart-doc-maven-plugin 1.2.0`, the plugin can automatically analyze and generate the module's dependencies to load the necessary source code, and it won't merge all module interfaces into a single document.** \ No newline at end of file diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index 529d763..0478417 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -19,8 +19,8 @@ - 插件使用进阶 - [maven插件使用进阶](zh-cn/plugins/maven_plugin.md "maven插件") - [maven插件调试](zh-cn/plugins/maven-plugin-debug.md "maven插件调试") - - [gradle插件使用进阶](zh-cn/plugins/gradle_plugin.md "maven插件") - - [gradle插件调试](zh-cn/plugins/gradle_plugin_debug.md "maven插件调试") + - [gradle插件使用进阶](zh-cn/plugins/gradle_plugin.md "gradle插件") + - [gradle插件调试](zh-cn/plugins/gradle_plugin_debug.md "gradle插件调试") - FAQ使用常见问题 - [使用问题集](zh-cn/faq.md) - [文档效果](zh-cn/docsImages.md) diff --git a/docs/zh-cn/plugins/gradle_plugin.md b/docs/zh-cn/plugins/gradle_plugin.md index 690a03b..0c9927d 100644 --- a/docs/zh-cn/plugins/gradle_plugin.md +++ b/docs/zh-cn/plugins/gradle_plugin.md @@ -41,7 +41,7 @@ apply(plugin = "com.ly.smart-doc") **`buildscript`配置添加到`build.gradle`的顶部** 。 ### Plugin options -是`smart-do`c插件使用还需要在`build.gradle`添加一些常见本身的配置 +使用`smart-doc`插件还需要在`build.gradle`添加一些常见本身的配置 | Option | Default value | Required| Description | | ------ | ------------- | -------------|-------------------------------------------------------------------------------------------------| diff --git a/docs/zh-cn/plugins/maven-plugin-debug.md b/docs/zh-cn/plugins/maven-plugin-debug.md index d8b93e3..fda154a 100644 --- a/docs/zh-cn/plugins/maven-plugin-debug.md +++ b/docs/zh-cn/plugins/maven-plugin-debug.md @@ -3,7 +3,7 @@ 官方并不能根据这些简单的错误信息来解决问题，因为用户的使用环境和所写的代码都是我们无法模拟的。 因此我们希望使用`smart-doc-maven-plugin`的用户在报错时能够通过`debug`来获取到更详细的信息。 在提`issue`时添加详细的问题描述，这样也能帮助我们更加快速的修改问题。 -下面将介绍如来调试`smart-doc-maven-plugin`插件。 +下面将介绍如何来调试`smart-doc-maven-plugin`插件。 # 添加smart-doc依赖 因为`smart-doc-maven-plugin`最终是使用`smart-doc`来完成项目的源码分析和文档生成的， diff --git a/docs/zh-cn/plugins/maven_plugin.md b/docs/zh-cn/plugins/maven_plugin.md index 405c1dd..cf46f9a 100644 --- a/docs/zh-cn/plugins/maven_plugin.md +++ b/docs/zh-cn/plugins/maven_plugin.md @@ -164,7 +164,7 @@ mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc // 生成dubbo接口文档推送到torna mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc ``` -在使用`mvn`命令构建是如果想查看`debug`日志，`debug`日志也能够帮助你去分析`smart-doc-maven`插件的源码加载情况，可以加一个`-X`参数。例如： +在使用`mvn`命令构建时如果想查看`debug`日志，`debug`日志也能够帮助你去分析`smart-doc-maven`插件的源码加载情况，可以加一个`-X`参数。例如： ``` mvn -X -Dfile.encoding=UTF-8 smart-doc:html ``` @@ -224,7 +224,7 @@ mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web2 -am [【多模块测试用例参考】](https://gitee.com/smart-doc-team/spring-boot-maven-multiple-module) -**注意：** **怎么去使用插件并没有固定的模式，最重要的是熟练`Maven`的一些列操作，然后根据自己的项目情况来调整。技巧娴熟就能应对自如。 +**注意：** **怎么去使用插件并没有固定的模式，最重要的是熟练`Maven`的一些操作，然后根据自己的项目情况来调整。技巧娴熟就能应对自如。 对于插件的使用，从`smart-doc-maven-plugin 1.2.0`开始，插件是能够自动分析生成模块的依赖来加载必要的源码， 并不会将所有模块的接口文档合并到一个文档中。** From c40a2f461fa9fb747b5d8c80100c9773516009ef Mon Sep 17 00:00:00 2001 From: Rancho-7 <1027229497@qq.com> Date: Sun, 29 Oct 2023 18:11:53 +0800 Subject: [PATCH 6/6] adjust --- docs/_sidebar.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 93b5c4b..c6ff213 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -18,5 +18,5 @@ - [Changelog](changelog.md "Changelog") - Advanced Plugin Usage - - [maven插件使用进阶](en/plugins/maven_plugin.md "maven插件") - - [maven插件调试](en/plugins/maven-plugin-debug.md "maven插件调试") + - [Advanced use of maven plugin](en/plugins/maven_plugin.md "maven插件") + - [Maven plugin debugging](en/plugins/maven-plugin-debug.md "maven插件调试")