maven site plugin

Owned by 정광섭
Last updated: 2015-Aug-23
3 min read

Intro

 Site Plugin 은 project site 를 생성하기 위한 플러그인으로 생성된 사이트는 POM 에 설정된 프로젝트 리포트를 포함하고 있다. 프로젝트의 문서나 기타 리포팅 정보를 빌드시에 자동으로 생성할 때 유용하다.

Goals

 

  • site:site is used generate a site for a single project. Note that links between module sites in a multi module build will not work, since local build directory structure doesn't match deployed site.
  • site:deploy is used to deploy the generated site using Wagon supported protocol to the site URL specified in the <distributionManagement> section of the POM.
  • site:run starts the site up, rendering documents as requested for faster editing. It uses Jetty as the web server.
  • site:stage generates a site in a local staging or mock directory based on the site URL specified in the <distributionManagement> section of the POM. It can be used to test that links between module sites in a multi module build works.
  • site:stage-deploy deploys the generated site to a staging or mock directory to the site URL specified in the <distributionManagement> section of the POM.
  • site:attach-descriptor adds the site descriptor (site.xml) to the list of files to be installed/deployed. For more references of the site descriptor, here's a link.
  • site:jar bundles the site output into a JAR so that it can be deployed to a repository.
  • site:effective-site calculates the effective site descriptor, after inheritance and interpolation.

Creating a site

Creating Content

site contents 는 관례에 따라 ${basedir}/src/site 에 저장한다. 

Customizing the Look & Feel

custom css 를 사용할 수 있지만 skin 을 사용하는 것을 추천한다. skin 목록은 http://maven.apache.org/skins/ 에서 볼 수 있다. 개인적으로는 Twitter's Bootstrap 을 사용하는 maven-fluido-skin가 제일 깔끔하고 다양한 기능을 제공하고 있어서 사용한다.

 

Creating a Site Descriptor

src/site 폴더밑에 site.xml 을 만들어서 site 의 layout, 사용할 skin 등을 지정할 수 있다.

site.xml 예제
<?xml version="1.0" encoding="UTF-8"?>
<project name="Maven Project">
  <bannerLeft>
    <name>Maven</name>
    <src>http://maven.apache.org/images/apache-maven-project.png</src>
    <href>http://maven.apache.org/</href>
  </bannerLeft>
  <bannerRight>
    <src>http://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <links>
      <item name="Apache" href="http://www.apache.org/" />
      <item name="Maven 1.x" href="http://maven.apache.org/maven-1.x/"/>
      <item name="Maven 2" href="http://maven.apache.org/"/>
    </links>

    <menu name="Maven 2.0">
      <item name="Introduction" href="index.html"/>
      <item name="Download" href="download.html"/>
      <item name="Release Notes" href="release-notes.html" />
      <item name="General Information" href="about.html"/>
      <item name="For Maven 1.x Users" href="maven1.html"/>
      <item name="Road Map" href="roadmap.html" />
    </menu>

    <menu ref="reports"/>
    <skin>
        <groupId>org.apache.maven.skins</groupId>
        <artifactId>maven-fluido-skin</artifactId>
        <version>1.3.1</version>
  </skin>
    ...
  </body>
</project>

 

<menu ref="reports"/> 부분은 mvn site 실행시 생성된 프로젝트 리포트 메뉴와 링크로 대치된다.

 

Configuring Reports

 

Usage

Generating Site

사이트는 기본적으로 target/site/ 에 생성된다.

mvn site

생성된 site 는 site:run goal 로 jetty WAS 를 띄워서 브라우저에서 http://localhost:8080 을 통해 볼 수 있다. (또는 target/site/index.html 을 브라우저에서 읽어도 된다._

mvn site:run

 

Deploying Site

사전에 POM 에 distributionManagement 가 설정되어 있어야 한다.

<project>
  ...
  <distributionManagement>
    <site>
      <id>www.yourcompany.com</id>
      <url>scp://www.yourcompany.com/www/docs/project/</url>
    </site>
  </distributionManagement>
  ...
</project>
mvn site:deploy

생성과 deploy 를 한 번에 하려면 다음 유틸리티 goal 을 사용하면 된다.

mvn site-deploy

 

 

Javadoc 을 remote 에 upload 하기

 

scp 를 이용하여 remote 에 upload 할 수 있다. Upload 된 javadoc 는 Web 를 통해 review 할 수 있으며 Confluence 의 html-include macro 를 사용하여 Page 에서 바로 참고 가능하다.

이 기능을 사용하려면 Project report 에서 javadoc 을 생성하게 pom 파일을 변경해야 한다.

 

settings.xml 설정

<servers>
  <server>
    <id>javadocServer</id>
    <username>javadoc</username>
    <password>javadocPwd</password>
    <configuration>
	</configuration>
  </server>
</servers>

pom.xml 설정

distributionManagement의 URL 에 ssh 를 사용하려면 wagon-ssh 가 필요하다.

<reporting>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-javadoc-plugin</artifactId>
			<version>2.9.1</version>
			<configuration>
			</configuration>			
		</plugin>
	</plugins>
</reporting>
<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-site-plugin</artifactId>
			<version>3.3</version>
			<dependencies>
				<dependency>
					<groupId>org.apache.maven.wagon</groupId>
					<artifactId>wagon-ssh</artifactId>
					<version>2.6</version>
				</dependency>
			</dependencies>
		</plugin>
	</plugins>
</build>
<distributionManagement>
    <site>
        <id>javadocServer</id>
        <url>scp://myserver/var/www/html/javadoc/${project.artifactId}</url>
    </site>
</distributionManagement>

적용

mvn site-deploy

TroubleShooting

site-deploy 실패

다음과 같은 메시지가 발생하고 site-deploy 가 실패하는 경우가 있다.

Unable to configure Wagon: 'scp': While configuring wagon for 'java-doc': Unable to apply wagon configuration. Cannot find setter, adder nor field in org.apache.maven.wagon.providers.ssh.jsch.ScpWagon for 'sshExecutable' -> [Help 1]

원인은 오래된 site plugin 문서에서는 scpExecutable, sshExecutable 등으로 실행할 ssh, scp 프로그램을 지정하라고 되어 있으나 wagon-ssh 는 Pure Java로 구현된 jsch라는 ssh client를 내장하고 있다. Pure Java 이므로 외부 프로그램이 필요없으므로 아래와 같은 setter 가 없어서 발생하는것이니 scpExecutable, sshExecutable 항목이 있으면 삭제하면 된다.

 

maven site 가 느릴때

mvn site 시에 다음과 같은 메시지가 출력되고 시간이 오래 걸림

Generating "Dependencies" report    --- maven-project-info-reports-plugin:2.7

프로젝트에 사용된 library 의 의존성 확인을 위해 remote repository 에 연결하여 시간이 오래 걸림.

처리방법

  1. -o 옵션으로 offline 모드로 구동

    mvn -o site-deploy

  2. reporting 항목의 maven-project-info-reports-plugin 에서 dependencyLocationsEnabled  를 false 로 설정

    pom.xml
    <reporting>
    <plugins>
 
	<plugin>
		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-project-info-reports-plugin</artifactId>
		<version>2.7</version>
 
		<configuration>
		  <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
		</configuration>
	</plugin>
 
    </plugins>
  </reporting>

     

참고 자료