[doc] document for each rule a sample how to reference it

pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java

@@ -239,15 +239,16 @@ public class RuleDocGenerator {
         for (Map.Entry<Language, List<RuleSet>> entry : rulesets.entrySet()) {
             String languageTersename = entry.getKey().getTerseName();
             for (RuleSet ruleset : entry.getValue()) {
+                String rulesetFilename = getRuleSetFilename(ruleset);
                 String filename = RULESET_INDEX_FILENAME_PATTERN
                     .replace("${language.tersename}", languageTersename)
-                    .replace("${ruleset.name}", getRuleSetFilename(ruleset));
+                    .replace("${ruleset.name}", rulesetFilename);
 
                 Path path = getAbsoluteOutputPath(filename);
 
                 String permalink = RULESET_INDEX_PERMALINK_PATTERN
                         .replace("${language.tersename}", languageTersename)
-                        .replace("${ruleset.name}", getRuleSetFilename(ruleset));
+                        .replace("${ruleset.name}", rulesetFilename);
 
                 List<String> lines = new LinkedList<>();
                 lines.add("---");
@@ -350,6 +351,12 @@ public class RuleDocGenerator {
                         }
                         lines.add("");
                     }
+
+                    lines.add("**Use this rule by referencing it:**");
+                    lines.add("``` xml");
+                    lines.add("<rule ref=\"rulesets/" + languageTersename + "/" + rulesetFilename + ".xml/" + rule.getName() + "\" />");
+                    lines.add("```");
+                    lines.add("");
                 }
 
                 writer.write(path, lines);

pmd-doc/src/test/resources/expected/sample.md

@@ -21,6 +21,11 @@ Just some description of a deprecated rule.
 //ForStatement
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/DeprecatedSample" />
+```
+
 ## JumbledIncrementer
 
 **Since:** PMD 1.0
@@ -58,6 +63,11 @@ public class JumbledIncrementerRule1 {
 |----|-------------|-----------|
 |sampleAdditionalProperty|the value|This is a additional property for tests|
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/JumbledIncrementer" />
+```
+
 ## MovedRule
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -93,6 +103,11 @@ public class JumbledIncrementerRule1 {
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/MovedRule" />
+```
+
 ## OverrideBothEqualsAndHashcode
 
 **Since:** PMD 0.4
@@ -132,6 +147,11 @@ public class Foo {      // perfect, both methods provided
 }
 ```
 
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/OverrideBothEqualsAndHashcode" />
+```
+
 ## RenamedRule
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
@@ -172,3 +192,8 @@ public class JumbledIncrementerRule1 {
 |Name|Default Value|Description|
 |----|-------------|-----------|
 |sampleAdditionalProperty|the value|This is a additional property for tests|
+
+**Use this rule by referencing it:**
+``` xml
+<rule ref="rulesets/java/sample.xml/RenamedRule" />
+```