Issue #17691 : Website Generation doesn't automatically reflect new c… by smita1078 · Pull Request #18217 · checkstyle/checkstyle

smita1078 · 2025-11-30T15:48:37Z

This PR introduces a new macro generate-checks-indexes to automatically generate category-specific index pages for Checkstyle checks. This macro works similarly to the existing allCheckSummaries macro but generates per-category index tables.

Problem

Previously, category index pages (e.g., src/site/xdoc/checks/javadoc/index.xml) had to be manually maintained. When check descriptions changed in Javadoc, these index files would become outdated, requiring manual updates to keep them in sync.

Solution

Implemented a Maven Doxia macro that:

Scans all Check and Holder Java files in the source tree
Extracts summaries from Javadoc @since tagged descriptions
Groups checks by category (annotation, blocks, coding, design, etc.)
Generates HTML table rows for each category with check name and summary
Handles special cases:
- Category remapping (e.g., indentation → misc)
- Explicit category assignments (e.g., SuppressWarningsHolder → annotation)
- Separate "Holder Checks" sections when applicable

romani

Good progress !!!

This macro works similarly to the existing allCheckSummaries macro but generates per-category index tables.

why we cannot update existing to have "package" as optional paramter ?

items:

smita1078 · 2025-11-30T17:38:23Z

This macro works similarly to the existing allCheckSummaries macro but generates per-category index tables.

why we cannot update existing to have "package" as optional paramter ?

Can be done will explore this option as well

smita1078 · 2025-12-02T05:02:18Z

github, generate site

github-actions · 2025-12-02T05:14:17Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/annotation/index.html#

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/blocks/index.html#Blocks_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/coding/index.html#Coding_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/design/index.html#Design_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/header/index.html#Headers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/imports/index.html#Imports_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/javadoc/index.html#Javadoc_Comments_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/metrics/index.html#Metrics_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/misc/index.html#Miscellaneous_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/modifier/index.html#Modifiers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/naming/index.html#Naming_Conventions_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/regexp/index.html#Regexp_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/sizes/index.html#Size_Violations_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4e6b9ea_20251202051348/checks/whitespace/index.html#Whitespace_Checks

smita1078 · 2025-12-02T05:39:30Z

why we cannot update existing to have "package" as optional paramter ?

Done

romani

items:

romani · 2025-12-02T13:31:07Z

@stoyanK7 , please help to review this PR

stoyanK7

Looks good overall 👍 , three minor things (apart from the indentation that is already commented on)

stoyanK7 · 2025-12-02T14:58:52Z

+        if (isHolder && "SuppressWarningsHolder".equals(simpleName)) {
+            packageName = ANNOTATION_PACKAGE;
+        }
+        else if (isHolder && "SuppressXpathWarningsHolder".equals(simpleName)) {
+            packageName = ANNOTATION_PACKAGE;
+        }


This could be simplified to

Suggested change

if (isHolder && "SuppressWarningsHolder".equals(simpleName)) {

packageName = ANNOTATION_PACKAGE;

}

else if (isHolder && "SuppressXpathWarningsHolder".equals(simpleName)) {

packageName = ANNOTATION_PACKAGE;

}

if (isHolder) {

packageName = ANNOTATION_PACKAGE;

}

Can't resolve thread but it's done.

romani · 2025-12-03T16:59:22Z

GitHub, generate website

github-actions · 2025-12-03T17:02:49Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/annotation/index.html#

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/coding/index.html#Coding_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/design/index.html#Design_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/header/index.html#Headers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/imports/index.html#Imports_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/javadoc/index.html#Javadoc_Comments_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/metrics/index.html#Metrics_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/misc/index.html#Miscellaneous_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/modifier/index.html#Modifiers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/naming/index.html#Naming_Conventions_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/regexp/index.html#Regexp_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/sizes/index.html#Size_Violations_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/ac8fed0_20251203170216/checks/whitespace/index.html#Whitespace_Checks

romani · 2025-12-05T21:31:53Z

@stoyanK7, please do comment and approval as you finish.

@smita1078 , please reply "done" to all addressed items. Let's not keep rooms for misunderstanding in this PR.

smita1078 · 2025-12-06T02:48:26Z

github, generate site

github-actions · 2025-12-06T02:51:42Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks.html#Standard_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/annotation/index.html#

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/coding/index.html#Coding_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/design/index.html#Design_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/header/index.html#Headers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/imports/index.html#Imports_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/javadoc/index.html#Javadoc_Comments_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/metrics/index.html#Metrics_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/misc/index.html#Miscellaneous_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/modifier/index.html#Modifiers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/naming/index.html#Naming_Conventions_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/regexp/index.html#Regexp_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/sizes/index.html#Size_Violations_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1027983_20251206025104/checks/whitespace/index.html#Whitespace_Checks

stoyanK7 · 2025-12-06T09:02:57Z

Did one final pass and everything looks good. Nice work, @smita1078 !

Approved 👍

smita1078 · 2025-12-06T18:47:35Z

github, generate site

github-actions · 2025-12-06T18:55:01Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks.html#Standard_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/annotation/index.html#

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/coding/index.html#Coding_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/design/index.html#Design_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/header/index.html#Headers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/imports/index.html#Imports_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/javadoc/index.html#Javadoc_Comments_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/metrics/index.html#Metrics_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/misc/index.html#Miscellaneous_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/modifier/index.html#Modifiers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/naming/index.html#Naming_Conventions_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/regexp/index.html#Regexp_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/sizes/index.html#Size_Violations_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/9ba4e93_20251206185350/checks/whitespace/index.html#Whitespace_Checks

romani

Very good.
Item from me:

romani · 2025-12-07T03:02:34Z

  <!-- no since in module by design -->
  <suppress id="sinceMacroMustExist"
-            files="src[\\/]site[\\/]xdoc[\\/]checks\.xml\.template"/>
+            files="src[\\/]site[\\/]xdoc[\\/]checks([\\/][a-z]+)?[\\/]index\.xml\.template|src[\\/]site[\\/]xdoc[\\/]checks\.xml\.template|src[\\/]site[\\/]xdoc[\\/]checks[\\/][a-z]+\.xml"/>


Instead of complicated to read single suppression tag, let's have few tags with simple content for "files" attribute.
It will be a way easier to maintain it, and it can have special excuse comment to explain reason of suppression.
Apply to all others.

romani · 2025-12-07T03:11:43Z

@stoyanK7, for future you can approve in GitHub UI, it will keep gray check mark, very clear signal that you approved PR. Approval by comment might be not easy to find in long PR.

stoyanK7

@romani Just found the button. I thought I had no permissions to approve, because I could not find an approval button, but it turns out it's not where I am used to finding it.

…ect new changes to index.xml for checks

smita1078 · 2025-12-07T11:02:03Z

github, generate site

github-actions · 2025-12-07T11:05:38Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks.html#Standard_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/annotation/index.html#

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/coding/index.html#Coding_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/design/index.html#Design_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/header/index.html#Headers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/imports/index.html#Imports_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/javadoc/index.html#Javadoc_Comments_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/metrics/index.html#Metrics_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/misc/index.html#Miscellaneous_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/modifier/index.html#Modifiers_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/naming/index.html#Naming_Conventions_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/regexp/index.html#Regexp_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/sizes/index.html#Size_Violations_Checks

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8249db4_20251207110457/checks/whitespace/index.html#Whitespace_Checks

smita1078 · 2025-12-07T15:50:27Z

All done 👍
I am not able to understand why ci/semaphore is failing

romani · 2025-12-07T16:06:39Z

Everyone is welcome to review PRs, the more reviews the better, and even approve. Maintainers are who take responsibility to do final check that all is good and merge.

romani

Crazy complicated update.
Impressive work.
This huge leap forward., I hope future contributors appreciate simplicity to write new Check

smita1078 force-pushed the newBranchMacro branch from c7d0139 to 82b2eea Compare November 30, 2025 15:56

romani mentioned this pull request Nov 30, 2025

Xdoc marco to put version in xdoc from 'since' javadoc tag on Check #18218

Closed

smita1078 force-pushed the newBranchMacro branch from 82b2eea to 6f2c1b4 Compare November 30, 2025 16:09

romani requested changes Nov 30, 2025

View reviewed changes

Comment thread src/site/xdoc/checks/annotation/index.xml Outdated

Comment thread src/site/xdoc/checks/annotation/index.xml Outdated

Comment thread src/site/xdoc/checks/annotation/index.xml.template Outdated

Comment thread config/checkstyle-non-main-files-suppressions.xml Outdated

smita1078 force-pushed the newBranchMacro branch 5 times, most recently from 3375c5e to 4e6b9ea Compare December 2, 2025 04:18

romani requested changes Dec 2, 2025

View reviewed changes

Comment thread src/site/xdoc/checks/annotation/index.xml Outdated

Comment thread src/site/xdoc/checks/annotation/index.xml.template Outdated

stoyanK7 suggested changes Dec 2, 2025

View reviewed changes

smita1078 force-pushed the newBranchMacro branch 7 times, most recently from bfa9d8f to ac8fed0 Compare December 3, 2025 15:22

stoyanK7 reviewed Dec 4, 2025

View reviewed changes

Comment thread src/site/xdoc/checks/coding/index.xml Outdated

stoyanK7 reviewed Dec 4, 2025

View reviewed changes

Comment thread src/site/xdoc/checks/coding/index.xml

smita1078 force-pushed the newBranchMacro branch 3 times, most recently from 7caae3b to 1027983 Compare December 5, 2025 16:13

smita1078 commented Dec 6, 2025

View reviewed changes

Comment thread src/site/xdoc/checks/coding/index.xml Outdated

smita1078 force-pushed the newBranchMacro branch 3 times, most recently from dd40d2c to 9ba4e93 Compare December 6, 2025 18:31

romani requested changes Dec 7, 2025

View reviewed changes

stoyanK7 approved these changes Dec 7, 2025

View reviewed changes

smita1078 force-pushed the newBranchMacro branch 6 times, most recently from 5178361 to 3334b81 Compare December 7, 2025 10:31

Issue checkstyle#17691: Website Generation doesn't automatically refl…

8249db4

…ect new changes to index.xml for checks

smita1078 force-pushed the newBranchMacro branch from 3334b81 to 8249db4 Compare December 7, 2025 10:43

romani approved these changes Dec 7, 2025

View reviewed changes

romani merged commit d9f53a1 into checkstyle:master Dec 7, 2025
122 of 123 checks passed

Uh oh!

Conversation

smita1078 commented Nov 30, 2025 • edited by romani Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Uh oh!

romani left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smita1078 commented Nov 30, 2025

Uh oh!

smita1078 commented Dec 2, 2025

Uh oh!

github-actions Bot commented Dec 2, 2025

Uh oh!

smita1078 commented Dec 2, 2025

Uh oh!

romani left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

romani commented Dec 2, 2025

Uh oh!

stoyanK7 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

stoyanK7 Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

stoyanK7 Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

smita1078 Dec 6, 2025

Choose a reason for hiding this comment

Uh oh!

stoyanK7 Dec 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

romani commented Dec 3, 2025

Uh oh!

github-actions Bot commented Dec 3, 2025

Uh oh!

Uh oh!

Uh oh!

romani commented Dec 5, 2025

Uh oh!

smita1078 commented Dec 6, 2025

Uh oh!

github-actions Bot commented Dec 6, 2025

Uh oh!

stoyanK7 commented Dec 6, 2025

Uh oh!

Uh oh!

smita1078 commented Dec 6, 2025

Uh oh!

github-actions Bot commented Dec 6, 2025

Uh oh!

romani left a comment

Choose a reason for hiding this comment

Uh oh!

romani Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

smita1078 Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

romani commented Dec 7, 2025

Uh oh!

stoyanK7 left a comment

Choose a reason for hiding this comment

Uh oh!

smita1078 commented Nov 30, 2025 •

edited by romani

Loading

romani left a comment •

edited

Loading