# Documentation and I18N
# Documenting Components
Igor provides an online help for every component that is documented. The help is opened by clicking the button in the parameter editor.
Component documentation must be in Markdown format and placed in the following directory in the classpath:
doc/
The file containing a component's documentation must be name like the component's type ID, e.g.
doc/custom-component.md
where custom-component
ist the component's type ID.
I18N of component documentation is supported by placing translated documentation files in subdirectories that are named like the respective locale.
E.g. a translated documentation in german for the custom component must be placed in a classpath directory like:
doc/de_DE/custom-component.md
If no translated documentation for the current user's locale is found, igor will fall back to the standard documentation (if it exists).
# I18N
Igor supports translation of categories, types and parameters of components. In order to use the translation you have to place properties files in the following directory in the classpath:
i18n/
E.g. the translation for your custom components could be placed in the file:
i18n/custom-labels.properties
Translations must be placed in subdirectories that are named like the respective locale.
E.g. a german translation for your custom components must be placed in:
i18n/de_DE/custom-labels.properties
All properties files from the classpath residing in an i18n/
directory will be used as message source for translations.
# I18N Example
For a custom component...
/**
* A custom action.
*/
@IgorComponent(categoryId = "custom-actions-category", typeId = "custom-action-type")
public class CustomAction extends BaseAction {
/**
* A sample parameter.
*/
@IgorParam
private boolean addMessage = true;
...
}
...the properties file might look like this:
# Category-ID label
custom-actions-category=Custom Actions
# Type-ID label
custom-action-type=Special Action
# Igor parameters of components:
custom-action-type.addMessage=Really add message?
The labels defined will be used in igor's UI and in generated component documentation.
# Generating Documentation
Since keeping code and documentation in sync is difficult, you can use the igor-maven-plugin to generate documentation of your custom components.
Java 17 Features
Igor uses JavaParser (opens new window) to parse component source files and generate documentation from them.
The parser supports Java only up to language level 15 at the moment. Since igor requires Java 17, you might use langueage features in components that lead to parser errors during documentation generation, e.g.:
[ERROR] Could not parse file AddDataAction.java (generated documentation
might be incomplete): (line 112,col 21) Use of patterns with instanceof is not
supported.
In these cases you should provide manual documentation for the respective component as described above.
In order to use the plugin you have to enable it your project's pom.xml
file:
<plugin>
<groupId>com.arassec.igor</groupId>
<artifactId>igor-maven-plugin</artifactId>
<version>0.6.6</version>
<executions>
<execution>
<goals>
<goal>DocGen</goal>
</goals>
</execution>
</executions>
</plugin>
The plugin will scan all igor components under src/main/java
and generate component documentation from the component's JavaDoc comments in the directory:
src/main/resources/doc-gen
The precedence to determine which documentation file to use, if multiple for the same type ID exist, is:
- First try manually created documentation for the user's current locale, e.g.
doc/de_DE/custom-component-type.md
- If that doesn't exist try default, manually created documentation under
doc/
, e.g.doc/custom-component-type.md
- If there is still no documentation found, try generated documentation under
doc-gen
, e.g.doc-gen/custom-component-type.md
The following HTML elements are converted to their Markdown equivalents during generation:
HTML Element | Generation Result |
---|---|
<h2>heading2</h2> ... <h6>heading6</h6> | # heading2 ... ###### heading6 |
<br> | \n\n |
<strong>text</strong> | **text** |
<b>text</b> | **text** |
<i>text<i> | *text* |
<a href="https://www.arassec.com">arassec</a> | [arassec](https://www.arassec.com) |
HTML tables | Markdown tables |
<pre>text</pre> | `text` |
<pre><code>text</code></pre> | \n```text```\n |
<p>text</p> | \n\ntext\n |
<ul><li>first</li><li>second</li></ul> | * first\n* second\n\n |
Due to changes in JavaDoc-Linting HTML <h1> headings are not supported anymore!
# Code-Gen Example
E.g. for the following component...
/**
* <h1>Custom Action</h1>
* An action providing <strong>really</strong> usefull functionality.
*/
@IgorComponent(categoryId = "custom-actions-category", typeId = "custom-action-type")
public class CustomAction extends BaseAction {
/**
* A sample parameter. For details see <a href="https://intra.net">here</a>.
*/
@IgorParam
private boolean addMessage = true;
...
}
... the following documentation would be generated:
# Custom Action
An action providing **really** usefull functionality.
## Parameters
The component can be configured by the following parameters:
Parameter | Description
:---|:---
addMessage | A sample parameter. For details see [here](https://intra.net)