What You Should Know before Installing
Before you install Acrolinx for SonarQube, make sure that you have the following software installed:
|Java Runtime Environment (JRE)||1.7|
|Acrolinx Server||4.3 or later|
|Jenkins Server (optional)||1.615|
Also make sure that Acrolinx for SonarQube is enabled in your Acrolinx license, otherwise you'll get a licensing error. You can check this in the Acrolinx server Dashboard . If you need a new license, contact your Acrolinx project consultant.
You'll receive the Acrolinx software files in a compressed zip file.
IntroductionYou can use the Acrolinx Plug-in for SonarQube to include language quality in your Continuous Inspection process.
This means that:
- Your build engineers can set up automated tests to check the quality of the language in your project documents and help resources.
- Your developers can reject builds if there are too many issues in some documents.
- Developers can also use tools like Maven and SonarQube Runner to check the language quality before checking the code quality.
- Project managers can also review the content quality for entire projects.
- Supported File Types
- Installing Acrolinx for SonarQube
- Configuring the Connection to the Acrolinx Server
- Enabling and Configuring the Acrolinx Coding Rules
- Configuring the Acrolinx Settings for a Project in the SonarQube Dashboard
- Adding the Acrolinx Widget to Your Project Dashboard
- Checking a Project
- Reviewing the Acrolinx Results
Acrolinx supports the following file types when working with SonarQube:
Acrolinx only checks code comments in Java files.
*.xml (you can add other extensions in the SonarQube settings)
The main installer for SonarQube server doesn't include an XML analysis plug-in. This means that you can't check XML files with the default SonarQube installation.
You have to download an extra plug-in so that SonarQube can read XML files. You can get that plug-in from sonarsource.com .
|HTML||*.html, *.htm, *.xhtm, *.xhtml,|
The following formats are only supported in Acrolinx for SonarQube versions 1.0.4 or later.
|Microsoft Word documents||*.docx|
NOTE: SonarQube can't decode these file formats completely so you can't review the issues inline in your content.
Instead, open the Issues page in SonarQube and filter for your project.
To install Acrolinx to SonarQube, follow these steps:
Extract the contents of the zip file to the following directory:
- Restart the SonarQube server.
Once you've installed Acrolinx, you should be able to configure the Acrolinx plug-in settings in the SonarQube web interface. The first thing you'll need to do is configure the connection to your Acrolinx server.
Before you do this, you might want to set up a dedicated user account on your Acrolinx server that SonarQube can use for checking. We recommend this if you use analytics reports that break down checking behavior by user. You can isolate the automated checking that is done through SonarQube by filtering for this dedicated user account.
To configure the Acrolinx connection to your Acrolinx server, follow these steps:
- Navigate to Settings > General Settings > Sonar-Acrolinx-Plugin
- Enter the address of your Acrolinx server.
- Enter the user name and password for the Acrolinx account that you want to use to connect to the Acrolinx server.
Enter the path to the directory where the file-type interpreters are stored.
These files help Acrolinx to interpret the supported file formats and are stored in a subdirectory of your main plug-in directory. The default path is:
- Click Save .
Acrolinx comes with a set of coding rules for each file supported type, but they're all disabled by default. You have to enable them first and set the severity level for each one.
There's a coding rule for each combination of file type and issue type. For example, grammar issues in text files, grammar issues in XML files, and so on. We recommend that you filter by file type first, then filter for all rules with the tag "Acrolinx". This makes the list of rules is more manageable.
To enable and configure the Acrolinx coding rules, follow these steps:
- Make sure you're logged in to SonarQube as an administrator.
- Open the Rules page, type "Acrolinx" in the Rules search box and press Enter.
- Click the name of a rule to open it, and in the Quality Profiles section, click Activate .
In the dialog box that appears, select your preferred quality profile and severity level, then click
Acrolinx for SonarQube comes with a built-in quality profile called "Acrolinx". If you want to test the Acrolinx rules first, you can activate the rules for this quality profile only and assign the quality profile to a test project.
When you're ready to use the rules in production you might assign the rules to a quality profile that contains all your project-specific coding rules such as error-handling or well-formedness rules.
- Repeat the process for all remaining Acrolinx coding rules.
If you have existing projects that you want to check, make sure that they're using a quality profile that contains Acrolinx rules.
You can do this in the Quality Profile section of your project settings.
Once you've enabled the Acrolinx coding rules, you'll need to configure the Acrolinx settings for each project. If you don't have any projects yet, check the SonarQube documentation for more details on how to create projects.
The most important settings that you'll need to configure are the Language and Rule set settings. You can't run any checks until you've configured these settings. You also have to configure these settings in the SonarQube plug-in configuration the first time you check a project .
The remaining settings have default values so you can leave them at their defaults if you want to get started quickly.
You can also configure the Acrolinx settings in your SonarQube plug-in rather than updating them in the SonarQube dashboard. However, you might use the SonarQube dashboard if you prefer to edit the settings in web interface rather than editing a plug-in configuration file.
To configure the project settings in the SonarQube dashboard, follow these steps:
- Open a project and in the Settings menu, select General Settings , then click the Acrolinx category.
Configure the checking language.
In the Checking Language field enter the language code of your checking language,
For example, for English you would enter "en", for German you would enter "de" and so on.
Configure the rule set
Enter the exact name of the rule set that you want to use. Make sure that you enter as it appears in your Acrolinx server installation. For example, see the Resources section of the Acrolinx dashboard.
Configure the type of issues to check for.
For each of the issue types, select "true" or "false" depending on whether you want Acrolinx to check for that issue type
- Configure the file format and character set.
- Click Save .
After you run an analysis on your projects, you'll want to see a summary of the Acrolinx results for each project. The easiest way to do this is to add an Acrolinx widget to your project Dashboards.
To add an Acrolinx widget to your project dashboards, follow these steps:
- Open a project and click Configure Widgets .
- In the section that appears, select the Acrolinx category.
- In the widget that appears, click Add widget .
When you run analysis on a project with SonarQube, Acrolinx automatically checks content quality for the supported file types in your project. There are many ways to analyze a project with SonarQube . The following analysis plug-ins fully support Acrolinx checking.
- SonarQube for Jenkins
- SonarQube for Maven
- SonarQube Runner
In each of these plug-ins, you can send the Acrolinx settings as part of the analysis configuration for a project. In other words, you can configure the Acrolinx settings for a project in your SonarQube plug-in, instead of the configuring them in the SonarQube project dashboard.
However, you must send your language and rule set the first time you check a project, even if they're configured in the SonarQube Dashboard.
If you use Jenkins to manage your software builds, you can include automated Acrolinx checking as part of a Jenkins build. If you don't have it already, install the SonarQube Plug-in for Jenkins first.
To include Acrolinx checking in a Jenkins build, follow these steps:
- Open the Configure page for your Jenkins project and in the Build section, click Add build step and select the action Invoke Standalone SonarQube Analysis.
section, add the following SonarQube project properties:
sonar.projectKey=xml:test sonar.projectName=XML Test sonar.projectVersion=1.0 sonar.sources=src sonar.sourceEncoding=UTF-8
After the SonarQube project properties, add the Acrolinx check settings.
Most settings have default values, but at a minimum, you'll need to configure the language and rule set as follows:
For a full list of the Acrolinx properties, see the Acrolinx for SonarQube properties reference .
Your project settings should look something like this:
After you build your project, you should see information about the analysis in the Jenkins console. This information includes details of the resources that were checked with Acrolinx.
If you use Maven to manage and build your Java-based projects, you can include automated Acrolinx checking as part of a Maven build. You must have Maven version 3.0+ or later to use Acrolinx for SonarQube with Maven.
If you don't have it already, install and configure the SonarQube Plug-in for Maven first. You should have already set up a project for analysis with SonarQube according to the SonarQube documentation .
To include Acrolinx checking in a Maven build, follow these steps:
file for your project and add the Acrolinx check settings.
Most settings have default values, but at a minimum, you'll need to configure the language and rule set as follows:
<properties> <acrolinx.language>en</acrolinx.language> <acrolinx.ruleset>US English</acrolinx.ruleset> </properties>
For a full list of the Acrolinx properties, see the Acrolinx for SonarQube properties reference .After you have set up your pom.xml , it might look something like this simple example:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>org.codehaus.sonar</groupId> <artifactId>example-java-maven</artifactId> <version>1.0-SNAPSHOT</version> <name>Java :: Simple Project :: SonarQube Maven</name> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <sonar.language>java</sonar.language> <acrolinx.language>en</acrolinx.language> <acrolinx.ruleset>US English</acrolinx.ruleset> <acrolinx.spelling>true</acrolinx.spelling> <acrolinx.grammar>true</acrolinx.grammar> <acrolinx.style>true</acrolinx.style> </properties> </project>
and build your project with the Maven command
while adding the command
as an extra argument like this:
mvn package sonar:sonar
If you want to test SonarQube analysis with Acrolinx before you include it in a build, you can use SonarQube Runner as a standalone analyzer.
Acrolinx for SonarQube works with SonarQube Runner 2.4 or later.
To check a project with SonarQube Runner, follow these steps:
- Create a file called “sonar-project.properties” in the directory that contains your project files.
Add the following properties to the file you just created:
# must be unique in a given SonarQube instance sonar.projectKey=<PROJECT_KEY> # this is the name displayed in the SonarQube UI sonar.projectName=<PROJECT_NAME> sonar.projectVersion=1.0 # Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows. # Since SonarQube 4.2, this property is optional if sonar.modules is set. # If not set, SonarQube starts looking for source code from the directory containing # the sonar-project.properties file. sonar.sources=src # Encoding of the source code. Default is default system encoding #sonar.sourceEncoding=UTF-8 ### Acrolinx for SonarQube Properties ### # Required acrolinx.language=<LANGUAGE_ID> acrolinx.ruleset=<RULE_SET_NAME> #Optional <OPTIONAL_PROPERTIES>
Replace the placeholder values such as
with the required settings.
You can find a list of all the optional properties, see the Acrolinx for SonarQube properties reference .You can use the following basic example as a reference:
# must be unique in a given SonarQube instance sonar.projectKey=dita:topics # this is the name displayed in the SonarQube UI sonar.projectName=DITA topics sonar.projectVersion=1.0 # Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows. # Since SonarQube 4.2, this property is optional if sonar.modules is set. # If not set, SonarQube starts looking for source code from the directory containing # the sonar-project.properties file. sonar.sources=src # Encoding of the source code. Default is default system encoding #sonar.sourceEncoding=UTF-8 ### Acrolinx for SonarQube Properties ### # Required acrolinx.language=en acrolinx.ruleset=Techpubs #Optional acrolinx.grammar=true acrolinx.spelling=true acrolinx.style=true acrolinx.termsets=Routers,Switches acrolinx.termstatuses=deprecated,admitted
- Open a command shell, navigate to the project root directory, and run the command sonar-runner .
After your project analysis has completed, you'll be able to review the Acrolinx results in the Acrolinx widget that appears on the project dashboard.
You can see a summary of the number of issues for each issue type.
To get more details about a particular issue type such as spelling, click the measure and you'll see a list of files in your project. Each file is listed with the issue count for that measure from lowest to highest.
The following screenshot shows an example of a summary for grammar issues.
- To see the contents of a file annotated with all issues, click the file name.
To see all the issues within the rule filter, click the
measure in the
Issues and Technical
You should then see the issues on the Rules page, where you can filter the rules by different criteria. To see only Acrolinx rules, filter for the Acrolinx tag.