In the earlier articles, we discussed about handling external dependencies in Maven and its different types of Maven repositories through which the actual dependency management is taken care by Maven. However, in this article, we are going to discuss the creation of project documents using Maven. We are going to take an existing Maven project (springframework.myfirstapp) as example for the creation of project documentation. We have to navigate to the project directory using command line where pom.xml file is located (here C:\work\project\springframework.myfirstapp) and issue ‘mvn site’ command. If there is a requirement of Maven plugins and JARS for creating the document and if they were not downloaded earlier then you will observe those artifacts to get automatically downloaded after issue of ‘mvn site’ command at this point of time on the command line.
Maven Command to generate Project Document
Microsoft Windows [Version 10.0.14393] (c) 2016 Microsoft Corporation. All rights reserved. C:\Users\Aparajita>cd C:\work\project\springframework.myfirstapp C:\work\project\springframework.myfirstapp>mvn site
Sample project pom.xml file
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.edunoix</groupId> <artifactId>springframework.myfirstapp</artifactId> <description>This is a demo project to demonstrate Project documents using Maven.</description> <version>0.0.1-SNAPSHOT</version> <packaging>jar</packaging> <name>springframework.myfirstapp</name> <url>http://maven.apache.org</url> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <build> <resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> <targetPath>${project.build.directory}</targetPath> </resource> </resources> </build> <repositories> <repository> <id>org.springframework.spring-core</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-core</url> </repository> <repository> <id>org.springframework.spring-webmvc</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-webmvc</url> </repository> <repository> <id>org.springframework.spring-test</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-test</url> </repository> <repository> <id>org.springframework.spring-aspects</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-aspects</url> </repository> <repository> <id>org.springframework.spring-jdbc</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-jdbc</url> </repository> <repository> <id>org.springframework.spring-jms</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-jms</url> </repository> <repository> <id>org.springframework.spring-messaging</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-messaging</url> </repository> <repository> <id>org.springframework.spring-orm</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-orm</url> </repository> <repository> <id>org.springframework.spring-oxm</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-oxm</url> </repository> <repository> <id>org.springframework.spring-tx</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-tx</url> </repository> <repository> <id>org.springframework.spring-webmvc-portlet</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-webmvc-portlet</url> </repository> <repository> <id>org.springframework.spring-websocket</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-websocket</url> </repository> <repository> <id>org.springframework.spring-instrument</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-instrument</url> </repository> <repository> <id>org.springframework.spring-instrument-tomcat</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-instrument-tomcat</url> </repository> <repository> <id>org.springframework.spring-context-support</id> <url>https://mvnrepository.com/artifact/org.springframework/spring-context-support</url> </repository> </repositories> <dependencies> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-core</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-webmvc</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-test</artifactId> <version>4.3.9.RELEASE</version> <scope>test</scope> </dependency> <!-- <dependency> <groupId>org.springframework</groupId> <artifactId>spring-aspects</artifactId> <version>4.3.9.RELEASE</version> </dependency> --> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-jdbc</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-jms</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-messaging</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-orm</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-oxm</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-tx</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-webmvc-portlet</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-websocket</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-instrument</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-instrument-tomcat</artifactId> <version>4.3.9.RELEASE</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context-support</artifactId> <version>4.3.9.RELEASE</version> </dependency> </dependencies> </project>
When you issue ‘mvn site’ command at the project path with above pom.xml file then Maven will initate building the project and the following logs will be observed.
Microsoft Windows [Version 10.0.14393] (c) 2016 Microsoft Corporation. All rights reserved. C:\Users\Aparajita>cd C:\work\project\springframework.myfirstapp C:\work\project\springframework.myfirstapp>mvn site [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building springframework.myfirstapp 0.0.1-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-site-plugin:3.3:site (default-site) @ springframework.myfirstapp --- [INFO] configuring report plugin org.apache.maven.plugins:maven-project-info-reports-plugin:2.9 [INFO] Relativizing decoration links with respect to project URL: http://maven.apache.org [INFO] Rendering site with org.apache.maven.skins: maven-default-skin: jar: 1.0 skin. [INFO] Generating "Dependencies" report --- maven-project-info-reports-plugin:2.9 [INFO] Generating "Dependency Convergence" report --- maven-project-info-reports-plugin:2.9 [INFO] Generating "Dependency Information" report --- maven-project-info-reports-plugin:2.9 [INFO] Generating "About" report --- maven-project-info-reports-plugin:2.9 [INFO] Generating "Plugin Management" report --- maven-project-info-reports-plugin:2.9 [INFO] Generating "Plugins" report --- maven-project-info-reports-plugin:2.9 [INFO] Generating "Summary" report --- maven-project-info-reports-plugin:2.9 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 08:19 min [INFO] Finished at: 2018-01-06T10:22:05-05:00 [INFO] Final Memory: 21M/152M [INFO] ------------------------------------------------------------------------ C:\work\project\springframework.myfirstapp>
Results
Once maven build is successful then you can observe that a new site directory has created within the target directory which contains the project documentation as shown below.
Viewing Project document
You can view Maven Project documents by navigating to C:\work\project\springframework.myfirstapp\target\site folder and clicking on the index.html file in order to see the project documentation as shown below.
Next, click on the ‘Summary’ link present on the left hand side of the screen to find the overall project summary as shown below.
Source Code for this Spring Framework – App
Doxia – Documentation-processing Engine
Doxia is a documentation-processing engine which is used by Maven to create project documentation. It reads multiple source formats and covert it into a common document model. There are two commonly used formats which are available to Maven for writing project documentation. The formats which are parsed by Doxia are as follows.
Name of Format |
Description |
Link |
XDoc | XDoc is a Maven 1.x documentation format and used to create regular project documents. | https://jakarta.apache.org/site |
FML | FML is used for FAQ documents creation. | https://maven.apache.org |
Conclusion: –
In this article, we discussed about the creation of the project documentation by using Maven along with a suitable project example.