Website Generation doesn't automatically reflect new changes to checks.xml and checks/<type>/index.xml

[Zopsss]

I have read check documentation: https://checkstyle.org/checks/xxxxxx/nameofaffectedcheck.html
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words

After modifying a Check’s summary (for example, AnnotationLocation), I observed the following:

After running mvn clean verify, the above change is reflected in annotationlocation.xml and AnnotationLocationCheck.xml

But it is not reflected in checks/annotation/index.xml, though XdocsCategoryIndexTest's tests fails and gives following errors:

[ERROR]   XdocsCategoryIndexTest.testAllChecksListedInCategoryIndexAndDescriptionMatches:132 Check 'AnnotationLocation' in index 'src\site\xdoc\checks\annotation\index.xml': index description is not a prefix of XDoc description.                            
expected to start with: Checks location of annotation on language elements.                                                     
but was               : Checks location of annotation on language elements testing. By default, Check enforce to locate annotati
ons before target element, annotation should be located on separate line from target element. This check also verifies that the annotations are on the same indenting level as the annotated element if they are not on the same line.                          
[ERROR]   XdocsPagesTest.testAllModulesPageInSyncWithModuleSummaries:335->validateModulesSyncWithTheirSummaries:391 The summary 
for module AnnotationLocation in the file "src\site\xdoc\checks.xml" should match the first sentence of the "Description" subsection for this module in the file "annotationlocation.xml"                                                                       
expected: Checks location of annotation on language elements testing.                                                           
but was : Checks location of annotation on language elements.                                                                   
[INFO]
[ERROR] Tests run: 5597, Failures: 2, Errors: 0, Skipped: 53

( screenshot showing that the summary is not updated )

We need to manually place the new summary. Instead of this, checks/annotation/index.xml should be able to automatically fetch the newly modified summary.

After manually placing the new summary into the index.xml file and running mvn clean verify again, the XdocsPagesTest.java fails and gives this error:

The summary for check AnnotationLocation in the file "src\site\xdoc\checks\annotation\index.xml" should match the summary for this check in the file "src\site\xdoc\checks.xml"
expected: Checks location of annotation on language elements.
but was : Checks location of annotation on language elements testing.
Expected :Checks location of annotation on language elements.
Actual   :Checks location of annotation on language elements testing.

( screenshot showing that the summary is not updated )

it is telling that checks/annotation/index.xml and checks.xml have different content. So to pass the test, we again need to manually put the new summary into checks.xml as well.

Problem

• checks/<type>/index.xml does not automatically pull the updated summary from the check’s Javadoc.

• checks.xml also requires a manual update to stay in sync with the modified Javadoc.

Expected Behavior

Both checks/<type>/index.xml and checks.xml should automatically fetch the updated summary from the check’s Javadoc, similar to how annotationlocation.xml and AnnotationLocationCheck.xml are updated.

[nigar-08]

Hi ,
The issue is that checks/annotation/index.xml and checks.xml are not templates, so XdocGenerator doesn’t update them automatically when Javadoc changes in AnnotationLocationCheck.java. That’s why tests fail and manual edits are currently needed.
I can work on extending the generator so these files automatically fetch the updated summaries from the Javadocs.

[Zopsss]

The issue is that checks/annotation/index.xml and checks.xml are not templates, so XdocGenerator doesn’t update them automatically when Javadoc changes in AnnotationLocationCheck.java.

Yes, that maybe the reason why we need to update docs manually.

Thank you for your interest in this issue. But if you're a beginner then we would recommend you to work on good-* issues first as this can be a bit tricky for you :)

After gaining some experience first, you can work on this issue.

[nigar-08]

I completely understand—I'll start with some good-* issues to get more familiar first.
If there are any specific beginner-friendly issues you’d recommend for me, I’d love to take a look at those too!

[Zopsss]

Please start from good-first-issues

[romani]

@nigar-08 ,
Please read and watch videos at Starting_Development.

[smita1078]

@Zopsss

Either we can Update the existing generator logic to automatically sync the latest Javadoc summary into checks.xml and category index files during doc generation.
Or we can Refactor to use a macro-based approach where summaries are fetched dynamically from the Javadoc at build time, the main idea would be to convert the existing static XML files into templates so they can dynamically pull summaries from the Check’s Javadoc.

which one should be prefer I can give it a try..

[Zopsss]

I think macro-based approach would be more cleaner. @romani wdyt?

[romani]

Macro based approach is better. Single special macro based that generate xml for section based on on package name.

checkstyle/src/site/xdoc/checks/sizes/index.xml

Line 9 in 67b17c3

<section name="Size Violations Checks">

So test execution, will generate from template files the final xdoc xml with all content that is required.
Validation will not be required after implementation.