Merge pull request #43 from Rancho-7/master

Fix typos in documentation && Translate maven plugin related documents from Chinese to English

docs/_sidebar.md

@@ -16,3 +16,7 @@
 - [Document Effect](docsImages.md)
 - [Expand Development](expand.md)
 - [Changelog](changelog.md "Changelog")
+
+- Advanced Plugin Usage
+  - [Advanced use of maven plugin](en/plugins/maven_plugin.md "maven插件")
+  - [Maven plugin debugging](en/plugins/maven-plugin-debug.md "maven插件调试")

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
 <plugin>
     <groupId>com.ly.smart-doc</groupId>
@@ -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

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
+<dependency>
+     <groupId>com.github.shalousun</groupId>
+     <artifactId>smart-doc</artifactId>
+     <version>[Latest version]</version>
+     <scope>test</scope>
+</dependency>
+```
+**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
+<dependency>
+    <groupId>com.github.shalousun</groupId>
+    <artifactId>smart-doc-maven-plugin</artifactId>
+    <version>【Latest version】</version>
+</dependency>
+```
+Then, follow similar steps to debug the source code of `smart-doc-maven-plugin`.

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
+<plugin>
+    <groupId>com.github.shalousun</groupId>
+    <artifactId>smart-doc-maven-plugin</artifactId>
+    <version>[Latest Version]</version>
+    <configuration> 
+        <configFile>./src/main/resources/smart-doc.json</configFile>  
+        <projectName>${project.description}</projectName>  
+        <includes>  
+            <!-- include the package used when using mybatis-plus's Page. -->
+            <include>com.baomidou:mybatis-plus-extension</include>
+            <!-- include mybatis-plus-core when using mybatis-plus's IPage-->
+            <include>com.baomidou:mybatis-plus-core</include>
+            <!-- include jpa -->
+            <include>org.springframework.data:spring-data-commons</include>             
+        </includes> 
+    </configuration>
+    <executions>
+        <execution>
+            <!--If you don't need to launch Smart-doc during compilation, comment out the 'phase'-->
+            <phase>compile</phase>
+            <goals>
+                <!--smart-doc provides goals such as HTML,OpenAPI,Markdown and more,which can be configured as needed-->
+                <goal>html</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
+## 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
+<includes>
+    <!-- include the package used when using mybatis-plus's Page. -->
+    <include>com.baomidou:mybatis-plus-extension</include>
+    <!-- include mybatis-plus-core when using mybatis-plus's IPage-->
+    <include>com.baomidou:mybatis-plus-core</include>
+    <!-- include jpa -->
+    <include>org.springframework.data:spring-data-commons</include>
+</includes>
+<includes>
+      <!--Load all dependencies with the groupId 'com.xxx'-->
+      <include>com.xxx:.*</include>
+</includes>
+```
+
+
+#### excludes
+
+When encountering situations where certain classes cannot be loaded during plugin execution, exclude the dependencies associated with those classes.
+
+```xml
+<excludes>
+     <!--Exclude MongoDB dependency-->
+     <exclude>org.springframework.boot:spring-boot-mongodb</exclude>
+</excludes>
+```
+
+####  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.**

docs/index.html

@@ -76,6 +76,7 @@
           }
         )
       ]
+
 
     }
   </script>