confluence-reporting-maven-plugin-4.5

{info:title=auto generated page}this page has been generated by plugin: [org.bsc.maven:maven-confluence-reporting-plugin|https://github.com/bsorrentino/maven-confluence-plugin]{info}
h2. Index
{panel}
{toc}
{panel}


h2. Description
plugin that document a project (using maven site style) and send result to a live confluence site [http://www.atlassian.com/software/confluence/]



----

h2. Plugin Goals
|| Name || Description ||
|[confluence-reporting:export|confluence-reporting-maven-plugin-4.5 - export]|Export a confluence page either in PDF or DOC|
|[confluence-reporting:deploy|confluence-reporting-maven-plugin-4.5 - deploy]|Generate Project's documentation in confluence's wiki format and deploy it|
|[confluence-reporting:help|confluence-reporting-maven-plugin-4.5 - help]|Display help information on confluence-reporting-maven-plugin.<br>
Call <code>mvn confluence-reporting:help -Ddetail=true -Dgoal=&lt;goal-name&gt;</code> to display parameter details.|
|[confluence-reporting:delete|confluence-reporting-maven-plugin-4.5 - delete]|Delete a confluence pageTitle|



----

h2. Repository

{quote}

From Release 3.0.1 this plugin is available from [MAVEN CENTRAL REPO|http://repo2.maven.org/maven2/]
If you want stay tune over modification, includes the following repository declaration in your POM

{code:title=plugin repository}
<pluginRepositories>

<!-- IF YOU WANT STAY TUNED ON UPDATE REMOVE COMMENT -->
<pluginRepository>
<id>sonatype-repo</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>

</pluginRepositories>
{code}

{quote}

h2. Usage

{quote}

Below examples of plugin declarations


h3. Basic Declaration

{code:xml}
<plugin>
<groupId>org.bsc.maven</groupId>

<title>my-site-generation-test</title>
<labels>
<label>test</label>
<label>confluence</label>
</labels>
<templateWiki>${basedir}/src/site/confluence/template.confluence</templateWiki>
<wikiFilesExt>.confluence</wikiFilesExt>
<serverId>confluence-server-id</serverId>
<properties>
<prop>the_text_value</prop><!-- SIMPLE TEXT -->
<prop1>classpath:plugin-report.properties</prop1><!-- FROM CLASSPATH -->
<prop2>file://${basedir}/confluence.html</prop2><!-- FROM FILE SYSTEM -->
</properties>
</configuration>
</plugin>
{code}

h3. Add labels

<parentPageTitle>Home</parentPageTitle><!-- PARENT PAGE IN THE GIVEN SPACE -->
<title>custom_title</title><!-- PAGE TITLE (default ${project.build.finalName}) - SINCE 3.1.3 -->

<labels>
<label>label_value_1</label>
<label>label_value_2</label>
</labels>
</configuration>
{code}

h3. Inject custom properties within template

<parentPageTitle>Home</parentPageTitle><!-- PARENT PAGE IN THE GIVEN SPACE -->
<title>custom_title</title><!-- PAGE TITLE (default ${project.build.finalName}) - SINCE 3.1.3 -->

<properties>

<scm-url>${project.scm.url}</scm-url>
<version>${project.version}</version>
<build>${build.number}</build>

<myprop>classpath:plugin-report.properties</myprop><!-- SINCE 3.2.4 -->
<htmlpage>file://${basedir}/src/main/resources/confluence.html</htmlpage><!-- SINCE 3.2.4 -->

</properties>

</configuration>
{code}

h3. Change wiki files extension

<parentPageTitle>Home</parentPageTitle><!-- PARENT PAGE IN THE GIVEN SPACE -->
<title>custom_title</title><!-- PAGE TITLE (default ${project.build.finalName} )- SINCE 3.1.3 -->

<templateWiki>${basedir}/src/site/confluence/template.confluence</templateWiki>
<wikiFilesExt>.confluence</wikiFilesExt>

</configuration>
{code}

{quote}

{tip:title=Authentication}

Put yours confluence credential within settings.xml as server

{noformat}
<server>
<id>my_confluence_server</id>
<username>my_user</username>
<password>my_password</password>
</server>
{noformat}

Take note that also [maven ecryption|http://maven.apache.org/guides/mini/guide-encryption.html#How_to_encrypt_server_passwords ] is supported

{tip}


h2. Use template variables

{quote}
By default the plugin use an internal template to generate confluence page. You can customize the generated page creating a personal template into folder *$\{basedir\}/src/site/confluence* named *template.wiki*.
The template can include all valid confluence contents plus the following built-in variables

h3. Built-In template variables

|| variable || description || example ||
| $\{project.summary} | project summary | |
| $\{project.scmManager} | scm information | |
| $\{project.dependencies} | dependencies | |
| $\{pageTitle} | title of page | confluence-reporting-maven-plugin-4.5 |
| $\{artifactId} | artifactId | confluence-reporting-maven-plugin |
| $\{version} | version | 4.5 |
| $\{gitlog.jiraIssues} | list of JIRA issuses, extracted from gitlog since start tag | |
| $\{gitlog.sinceTagName} | name of version tag to start extract JIRA issues | |


{tip:title=Tips & Tricks}

* How to refer to an image
bq. *\!$\{pageTitle}\^image_name!*.
* How to refer to a child's image within child page
bq. *\!$\{childTitle}\^image_name!*.
* How to refer to an attachment
bq. *\[$\{pageTitle}\^attachment_name]*.
* How to refer to a child's attachment within child page
bq. *\[$\{childTitle}\^attachment_name]*.
{tip}

h3. Git log template variables
Main idea is automated creating of release notes with list of resolved JIRA issues utilizing integration between JIRA and Confluence.
Prerequrements:
# Include JIRA issue key in git commit message
# Using git as SCM and using version tags in git

h4. Git log configuration options

* {{gitLogJiraIssuesEnable}} Set it to true for enabling substitution of $\{gitlog.jiraIssues} build-in variable. Default value is false.
* {{gitLogSinceTagName}} Parse git log commits since last occurrence of specified tag name.
* {{gitLogUntilTagName}} Parse git log commits until first occurrence of specified tag name.
* {{gitLogCalculateRuleForSinceTagName}} If specified, plugin will try to calculate and replace actual gitLogSinceTagName value based on current project version $\{project.version} and provided rule. Possible values are
** NO_RULE
** CURRENT_MAJOR_VERSION. For example 1.2.3 will be resolved to 1.0.0
** CURRENT_MINOR_VERSION. For example 1.2.3 will be resolved to 1.2.0
** LATEST_RELEASE_VERSION. For example, if latest known version from version tags is 1.0.1 and current artifact (not released) version is 2.0.0, it will be resolved to 1.0.1
* {{gitLogJiraProjectKeyList}} JIRA projects keys to extract issues from gitlog. By default it will try extract all strings that match pattern (A-Za-z+)-\d+
* {{gitLogTagNamesPattern}} The pattern to filter out tagName. Can be used for filter only version tags
* {{gitLogGroupByVersions}} Enable grouping by versions tag

h4. Sample produced output of $\{gitlog.jiraIssues} with gitLogGroupByVersions=true

!Home^gitlog-sample02.png!

{quote}


h2. Template example

{noformat}

{info:title=Useful Information}
This page has been generated by [maven-confluence-plugin|https://github.com/bsorrentino/maven-confluence-plugin]
{info}

{toc}

h1. Introduction

{panel}
project description
{panel}

h1. Usage

{panel}
How to use the project
{panel}

${project.summary}


${project.scmManager}


${project.dependencies}

{noformat}