We decided to move our documentation from the XDoc format to projectdoc on Confluence. This allows us to update the information independent of the release cycles of the products. Here are some tips on how to use projectdoc for this task.
Placeholder in Code Snippets
We use space properties to define the project's coordinates (and other properties) and use them to replace placeholders in code fragments.
Here is the snippet from the space homepage that defines the project coordinates as space properties.
These properties can then be used throughout the space to reference the current product version.
Here is the macro that takes advantage of these properties:
And here is the rendered result:
Transclude from Remote
In order to NCP (Never Copy Paste), we use transclusion macros to reference and show content from remote resources. For instance the System Transclusion Macro to display the contents of an XSD file stored in a Git repository:
The system identifier "git" references a space property.
The URL to resources in the Git repository is therefore only stored in one place.
It is usually advisable to reference information on the tag that matches your project coordinates. In this example we simply reference the master to always show the latest information.
The result is show on The smartics JBoss Modules XSD.
Displaying Project Artifact
With the Nexus Link Macro it is very easy render a link to the product of the project.
The link is clickable and references the JAR artifact on the Nexus server.
In this case we reference the application link instead of space properties.
