- Created by Robert Reiner on 20. Dec 2016
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
Version 1 Next »
Provide a standard documentation for users of a plugin for Maven.
- Categories
Summary
Teams whose builds depend on Maven and that use automation heavily typically end up in writing their own plugins for Maven. Although these plugins are often only released for internal use, developers who employ these plugins need to have access to proper documentation. Maven provides the Maven Plugin Plugin to create as much meaningful documentation automatically from the source code. While it is easy to add howtos and tutorials - which are typically not generated automatically - with the use of the Maven Site Plugin, having these documents as part of the Confluence collaboration platform often makes it easier to apply changes and add additional information off-sync with the plugin's release cycle. Having this information in Confluence also makes it easier for non-programmers to add valuable information.
To create a user documentation for a plugin for Maven the projectdoc for Maven Developers Add-on for the projectdoc Toolbox provides tools to import information from a Maven POM file. This way all properties specified by the developers are accessible as space properties by authors of the documentation.
The projectdoc for Maven Developers Add-on is available on the Atlassian Marketplace and on Bitbucket. It is still considered to be experimental. So expect to encounter some rough edges.
Please get in touch if you have suggestions for improving the add-on or fork it on Bitbucket!
This approach does require to create a Maven Site with all reports and to link to or transclude from this information. The Information Systems Extension provides macros to access information from remote servers.
Resources
Information Material
The following list of resources provides background information on creating and working documentation for Java libraries.
Resource | Short Description | Type |
---|---|---|
Get started with the projectdoc Toolbox: learning by doing | topic | |
A gentle introduction to page blueprints provided by doctype add-ons. The page blueprints are grouped semantically to make it easier for users to build a conceptual mind map for them. | topic | |
Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc. | topic | |
Space properties are defined for spaces and are accessed via the Space Property Macro. This tip goes into detail in how to use space properties with inheritence and extension pages. | topic | |
Lists the configuration options at space level. | topic | |
Add-on to extend the projectdoc Toolbox to integrate remote information systems. | topic | |
Add-on to extend projectdoc with an API to access on the web. | topic | |
Add-on to extend projectdoc for Confluence with Maven Tools. | topic |
Doctypes
The following doctypes provided page blueprints to create documentation for a Java library.
Resource | Short Description | Categories |
---|---|---|
Properties are part of the configuration options of a system. | ||
Metadata documents provide tables of simple key/value pairs. This information can be used as an aspect or as additional space properties to be available for reference on your wiki. | ||
Document a version of a product or service. | ||
Document requirements you impose on artifacts. Artifacts are created by processes defined and used by the team. This includes assemblies created by the build process, source code artifacts or reports. | ||
Describe the codes that are part of the product's API. | ||
Interfaces document how elements of the system communicate with elements of this and other systems. |
Macros
The following macros support creating or working with documentation for a Java library.
Resource | Short Description | Categories |
---|---|---|
Renders a space property value. | ||
Renders all properties referenced by the current space. | ||
Renders an image generated from an Enterprise Architect diagram, transcluded from a server. | ||
Transclude HTML content from a remote server. | ||
Links API documentation pages for Java elements. | ||
Renders a link to an artifact stored on a Nexus server. | ||
Renders an image transcluded from a remote server. | ||
Links to a resource on a server. | ||
Transclude content from a resource from a remote system. | ||
Transclude text content from a remote server. |
Related Use Cases
Resource | Short Description | Categories |
---|---|---|
Provide a standard documentation for users of a library for Java. | ||
Communicate the quality targets, context, and design drivers of your software architecture. |
- No labels