Installing and Using Acrolinx for SonarQube

Transcription

1 Installing and Using Acrolinx for SonarQube support.acrolinx.com /hc/en-us/articles/ installing-and-using-acrolinx-for-sonarqube Acrolinx Customer Care Today at 14:08 Unfollow From 1.1 onwards, we refer to " rule sets " as " writing guides. " Applies To Software Version Acrolinx for SonarQube 1.1 What You Should Know before Installing Before you install Acrolinx for SonarQube, make sure that you have the following software installed: Software Version SonarQube Server 5.6.3, 5.6.6, and 6.1 Java Runtime Environment (JRE) 1.8 Acrolinx Server 5.1 or later Jenkins Server (optional) 2.65 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. Introduction You can use Acrolinx 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 1/15

2 checking the code quality. Project managers can also review the content quality for entire projects. To get started, review the following tasks and concepts: 1. Supported File Types 2. Installing Acrolinx for SonarQube 3. Configuring the Connection to the Acrolinx Server 4. Enabling and Configuring the Acrolinx Coding Rules 5. Configuring the Acrolinx Settings for a Project in the SonarQube Dashboard 6. Adding the Acrolinx Widget to Your Project Dashboard 7. Checking a Project Include Acrolinx Checking in a Jenkins Build Include Acrolinx Checking in a Maven Build Check a Project with SonarQube Runner 8. Reviewing the Acrolinx Results Supported File Types Acrolinx supports the following file types when working with SonarQube: Type Text JSON Properties XML HTML Extension *.txt *.json *.properties *.xml *.html, *.htm, *.xhtm, *.xhtml, The following formats are only supported in Acrolinx for SonarQube versions or later. Microsoft Word documents PDF *.docx *.pdf Note that Acrolinx doesn't work consistently when checking PDFs. We recommend using the source document to check your content. 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. Back to Top Installing Acrolinx for SonarQube 2/15

3 To install Acrolinx to SonarQube, follow these steps: 1. Extract the contents of the zip file to the following directory: <SONARQUBE_INSTALL_DIR>/extensions/plugins 2. Restart the SonarQube server. Back to Top Configuring the Connection to the Acrolinx Server Once you've installed Acrolinx, you should be able to configure the Acrolinx 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: 1. Navigate to Administration > General Settings >Acrolinx 2. Enter the address of your Acrolinx server. 3. Enter the user name and password for the Acrolinx account that you want to use to connect to the Acrolinx server. 4. Click Save. If you're connecting to a secure Acrolinx server, on which you've installed Let's Encrypt certificates, but the Java version on your client machine doesn't support certificates from Let's Encrypt, then you need to import the 3/15

4 certificate manually. To import the certificate manually, follow these steps: 1. Download the 'lets-encrypt-x3-cross-signed.cer' file from cross-signed.der. 2. Import the certificate: 1. Open a command prompt and run the following command: Back to Top keytool -trustcacerts -keystore %JAVA_HOME%\jre\lib\security\cacerts -storepass <PASSWORD> -importcert -alias lets-encrypt-x3-cross-signed -file <DIR_PATH>\lets-encrypt-x3-cross-signed.cer The <PASSWORD> is your key store password. The <DIR_PATH> is the directory where you saved the downloaded certificate. Enabling and Configuring the Acrolinx Coding Rules 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: 1. Make sure you're logged in to SonarQube as an administrator. 2. Open the Rules page, type "Acrolinx" in the Rules search box and press Enter. You should be able to see the new Acrolinx coding rules listed. 3. Click the name of a rule to open it, and in the Quality Profiles section, click Activate. 4. In the dialog box that appears, select your preferred quality profile and severity level, then click Activate. 4/15

5 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. 5. Repeat the process for all remaining Acrolinx coding rules. 6. If you ve 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 Administration settings. Back to Top 5/15

6 Configuring the Acrolinx Settings for a Project in the SonarQube Dashboard 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 Writing guide 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: 1. Open a project and in the Administration menu, select General Settings, then click the Acrolinx category. 2. 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. 3. Configure the Writing guide Enter the exact name of the Writing guide that you want to use. Make sure that you enter as it appears in 6/15

7 your Acrolinx server installation. For example, see the Resources section of the Acrolinx dashboard. 4. 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 5. Configure the file format and character set. 6. Click Save. Back to Top Adding the Acrolinx Widget to Your Project Dashboard 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: 1. Open a project and navigate to Dashboards, go to Manage Dashboards and click Configure Widgets. 2. In the section that appears, select the Acrolinx category. 3. In the widget that appears, click Add widget. You should now have the Acrolinx widget on all project dashboards. 7/15

8 Back to Top Checking a Project 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. 1. SonarQube for Jenkins 2. SonarQube for Maven 3. 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 Writing guide the first time you check a project, even if they're configured in the SonarQube Dashboard. Back to Top Include Acrolinx Checking in a Jenkins Build 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: 1. 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. 2. In the Analysis properties 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 3. 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 Writing guide as follows: sonar.acrolinx.language= <CHECKING_LANGUAGE> sonar.acrolinx.writing.guide= <WRITING_GUIDE_NAME> For a full list of the Acrolinx properties, see the Acrolinx for SonarQube properties reference. Your project settings should look something like this: 8/15

9 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. Back to Top Include Acrolinx Checking in a Maven Build 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: 9/15

10 1. Open the pom.xml 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 Writing guide as follows: <properties> <sonar.acrolinx.language>en</sonar.acrolinx.language> <sonar.acrolinx.writing.guide> US English </sonar.acrolinx.writing.guide> </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=" xmlns:xsi=" xsi:schemalocation=" <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.acrolinx.language>en</sonar.acrolinx.language> <sonar.acrolinx.writing.guide>publications</sonar.acrolinx.writing.guide> <sonar.acrolinx.spelling>true</sonar.acrolinx.spelling> <sonar.acrolinx.grammar>false</sonar.acrolinx.grammar> <sonar.acrolinx.style>true</sonar.acrolinx.style> <sonar.acrolinx.reuse>true</sonar.acrolinx.reuse> <acrolinx.deprecated.terms>true</acrolinx.deprecated.terms> <acrolinx.valid.terms>true</acrolinx.valid.terms> <acrolinx.admitted.terms>true</acrolinx.admitted.terms> <acrolinx.new.terms>true</acrolinx.new.terms> <acrolinx.term.sets>smarttech</acrolinx.term.sets></properties> </project> 2. Save your pom.xml and build your project with the Maven command mvn while adding the command sonar:sonar as an extra argument like this: mvn package sonar:sonar After you build your project, you should see information about the analysis in your command shell. This information includes details of the resources that were checked with Acrolinx. 10/15

11 Back to Top Check a Project with SonarQube Runner 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: 1. Create a file called sonar-project.properties in the directory that contains your project files. 2. 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 sonar.acrolinx.language =<LANGUAGE_ID> sonar.acrolinx.writing.guide =<WRITING_GUIDE_NAME> #Optional <OPTIONAL_PROPERTIES> 3. Replace the placeholder values such as <PROJECT_KEY> and <OPTIONAL_PROPERTIES> with the required settings. 11/15

12 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 sonar.acrolinx.language=en sonar.acrolinx.writing.guide=techpubs #Optional sonar.acrolinx.grammar=true sonar.acrolinx.spelling=true sonar.acrolinx.style=true acrolinx.term.sets=routers,switches acrolinx.deprecated.terms=true acrolinx.admitted.terms=true 4. Open a command shell, navigate to the project root directory, and run the command sonar-runner. You should see information about the analysis in your command shell. This information includes details of the resources that were checked with Acrolinx 12/15

13 Back to Top Reviewing the Acrolinx Results 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. 13/15

14 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 Issues measure in the Issues and Technical debit widget. 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. 14/15

15 Back to Top Was this article helpful? Comments 15/15