[doc] List the rules of the additional rulesets

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

@@ -228,10 +228,48 @@ public class RuleDocGenerator {
                 lines.add("");
 
                 for (RuleSet ruleset : additionalRulesetsForLanguage) {
-                    String deprecation = isRuleSetDeprecated(ruleset) ? DEPRECATION_LABEL_SMALL : "";
-                    lines.add("*    " + ruleset.getName() + ": "
-                            + deprecation
-                            + getRuleSetDescriptionSingleLine(ruleset));
+                    boolean deprecated = RuleSetUtils.isRuleSetDeprecated(ruleset);
+
+                    String rulesetName = ruleset.getName() + " (`" + RuleSetUtils.getRuleSetClasspath(ruleset) + "`)";
+
+                    if (!deprecated) {
+                        lines.add("*   " + rulesetName + ":");
+                        lines.add("");
+                        lines.add("    " + getRuleSetDescriptionSingleLine(ruleset));
+                        lines.add("");
+                    } else {
+                        lines.add("*   " + rulesetName + ":");
+                        lines.add("");
+                        lines.add("    " + DEPRECATION_LABEL_SMALL + " This ruleset is for backwards compatibility.");
+                        lines.add("");
+                    }
+
+                    lines.add("    It contains the following rules:");
+                    lines.add("");
+                    StringBuilder rules = new StringBuilder();
+                    for (Rule rule : getSortedRules(ruleset)) {
+                        if (rules.length() == 0) {
+                            rules.append("    ");
+                        } else {
+                            rules.append(", ");
+                        }
+
+                        Rule resolvedRule = RuleSetUtils.resolveRuleReferences(rule);
+                        if (resolvedRule instanceof RuleReference) {
+                            // Note: deprecated rulesets contain by definition only rule references
+                            RuleReference ref = (RuleReference) resolvedRule;
+                            String otherLink = RULESET_INDEX_PERMALINK_PATTERN
+                                    .replace("${language.tersename}", languageTersename)
+                                    .replace("${ruleset.name}", RuleSetUtils.getRuleSetFilename(ref.getRuleSetReference().getRuleSetFileName()));
+
+                            rules.append("[").append(ref.getRule().getName()).append("](");
+                            rules.append(otherLink).append("#").append(ref.getName().toLowerCase(Locale.ROOT)).append(")");
+                        } else {
+                            rules.append(rule.getName());
+                        }
+                    }
+                    lines.add(rules.toString());
+                    lines.add("");
                 }
                 lines.add("");
             }
@@ -241,24 +279,6 @@ public class RuleDocGenerator {
         }
     }
 
-    /**
-     * A ruleset is considered deprecated, if it only contains rule references
-     * and all rule references are deprecated.
-     *
-     * @param ruleset
-     * @return
-     */
-    private boolean isRuleSetDeprecated(RuleSet ruleset) {
-        boolean result = true;
-        for (Rule rule : ruleset.getRules()) {
-            if (!(rule instanceof RuleReference) || !rule.isDeprecated()) {
-                result = false;
-                break;
-            }
-        }
-        return result;
-    }
-
     /**
      * Shortens and escapes (for markdown) some special characters. Otherwise the shortened text
      * could contain some unfinished sequences.

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

@@ -7,7 +7,9 @@ package net.sourceforge.pmd.docs;
 import org.apache.commons.io.FilenameUtils;
 import org.apache.commons.lang3.StringUtils;
 
+import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleSet;
+import net.sourceforge.pmd.lang.rule.RuleReference;
 
 public final class RuleSetUtils {
 
@@ -29,4 +31,51 @@ public final class RuleSetUtils {
         return FilenameUtils.getBaseName(StringUtils.chomp(rulesetFileName));
     }
 
+    /**
+     * A ruleset is considered deprecated, if it only contains rule references
+     * and all rule references are deprecated.
+     *
+     * @param ruleset
+     * @return
+     */
+    public static boolean isRuleSetDeprecated(RuleSet ruleset) {
+        boolean result = true;
+        for (Rule rule : ruleset.getRules()) {
+            if (!(rule instanceof RuleReference) || !rule.isDeprecated()) {
+                result = false;
+                break;
+            }
+        }
+        return result;
+    }
+
+    public static String getRuleSetClasspath(RuleSet ruleset) {
+        final String RESOURCES_PATH = "/resources/";
+        String filename = StringUtils.chomp(ruleset.getFileName());
+        int startIndex = filename.lastIndexOf(RESOURCES_PATH);
+        if (startIndex > -1) {
+            return filename.substring(startIndex + RESOURCES_PATH.length());
+        } else {
+            return filename;
+        }
+    }
+
+    /**
+     * Recursively resolves rule references until the last reference.
+     * The last reference is returned.
+     * If the given rule not a reference, the rule is returned.
+     *
+     * @param rule
+     * @return
+     */
+    public static Rule resolveRuleReferences(Rule rule) {
+        Rule result = rule;
+        Rule ref = rule;
+        while (ref instanceof RuleReference) {
+            // remember the last reference
+            result = ref;
+            ref = ((RuleReference) ref).getRule();
+        }
+        return result;
+    }
 }

pmd-doc/src/test/java/net/sourceforge/pmd/docs/RuleDocGeneratorTest.java

@@ -67,7 +67,10 @@ public class RuleDocGeneratorTest {
         RuleSetFactory rsf = new RuleSetFactory();
         RuleSet ruleset = rsf.createRuleSet("rulesets/ruledoctest/sample.xml");
 
-        generator.generate(Arrays.asList(ruleset).iterator(), Arrays.asList("rulesets/ruledoctest/sample-deprecated.xml"));
+        generator.generate(Arrays.asList(ruleset).iterator(),
+                Arrays.asList(
+                        "rulesets/ruledoctest/sample-deprecated.xml",
+                        "rulesets/ruledoctest/other-ruleset.xml"));
 
         assertEquals(3, writer.getData().size());
         FileEntry languageIndex = writer.getData().get(0);

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

@@ -15,4 +15,19 @@ folder: pmd/rules
 
 ## Additional rulesets
 
-*    Sample Deprecated: <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> Sample ruleset which only contains deprecated rule references.
+*   Other ruleset (`rulesets/ruledoctest/other-ruleset.xml`):
+
+    Ruleset which serves a specific use case, such as Getting Started.
+
+    It contains the following rules:
+
+    [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer), [OverrideBothEqualsAndHashcode](pmd_rules_java_sample.html#overridebothequalsandhashcode)
+
+*   Sample Deprecated (`rulesets/ruledoctest/sample-deprecated.xml`):
+
+    <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span>  This ruleset is for backwards compatibility.
+
+    It contains the following rules:
+
+    [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer), [OverrideBothEqualsAndHashcode](pmd_rules_java_sample.html#overridebothequalsandhashcode)
+

pmd-doc/src/test/resources/rulesets/ruledoctest/other-ruleset.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+
+<ruleset name="Other ruleset"
+    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
+  <description>
+Ruleset which serves a specific use case, such as Getting Started.
+  </description>
+
+    <rule ref="rulesets/ruledoctest/sample.xml/OverrideBothEqualsAndHashcode" />
+    <rule ref="rulesets/ruledoctest/sample.xml/JumbledIncrementer" />
+
+</ruleset>