Issue #13134: Implement examples macro and xdoc template parser#13357
Conversation
|
|
I disabled maven-enforcer and everything passed the issue with Either override maven-enforcer or disable the sub-dependencies this dependency brings in. We really just need it for compile time and only for the AbstractMacro class, unless you need something else. The actual doxia run should bring in its own versions it needs I would think. It looks like they may have been cleaning this up in 2.0.0-M7. Maven enforcer complains a lot less, and its only complaint is between doxia-core and reflections on the version of slf4j-api to use. |
|
|
|
||
| <subsection name="Examples" id="Examples"> | ||
| <p> | ||
| <p id="Example1-config"> |
There was a problem hiding this comment.
I added these ids in the templates. That's why they appear here.
Please refer to #13205 (comment). We want to be able to add anchors to the examples and it's easier for me if I add those anchors now.
|
@stoyanK7 please make CI reasonably happy before review, there are enough violations in IDEA and Sonar to change code a fair amount. |
| <!-- catch lines above 100 symbols --> | ||
| <property name="format" | ||
| value="^(?!(.*href=|.*http(s)?:|import |(.* )?package |.* files=|.*\.dtd| \* \{@code| \* com\.)).{101,}$"/> | ||
| value="^(?!(.*value=.*Example\d+|.*href=|.*http(s)?:|import |(.* )?package |.* files=|.*\.dtd| \* \{@code| \* com\.)).{101,}$"/> |
There was a problem hiding this comment.
The path value in macros tends to be long. Suppression is the first thing that came to mind.
<macro name="example">
<param name="path"
value="resources/com/puppycrawl/tools/checkstyle/checks/whitespace/filetabcharacter/Example4.xml"/>
<param name="type" value="code"/>
</macro>Another solution - we can split the path value into multiple lines and removeAll() whitespaces. I don't believe files in this repository are supposed to have spaces in file names anyways. Please let me know what you think.
<macro name="example">
<param name="path"
value="resources/com/puppycrawl/tools/checkstyle/checks
/whitespace/filetabcharacter/Example4.xml"/>
<param name="type" value="code"/>
</macro>There was a problem hiding this comment.
Please suppress path as we do for links
There was a problem hiding this comment.
So like it is right now?
|
Linkcheck is failing. Since the |
|
https://sonarcloud.io/dashboard?id=org.checkstyle%3Acheckstyle&pullRequest=13357
|
|
93 files changed .... Please move all section comments moving to separate PR to merge instantly. You can keep some draft PR to see and show changes for all modules. But acceptance will happen module by module or in small groups. |
|
Done. |
|
@romani Done. Snyk is resolved. |
| // We skip validation of examples section on modules that have this section generated | ||
| // until https://github.com/checkstyle/checkstyle/issues/13100 | ||
| private static final Set<String> MODULES_EXAMPLES_TO_SKIP = Set.of( | ||
| "WhitespaceAfter" |
There was a problem hiding this comment.
@nrmancuso Here is the update of XdocsJavaDocsTest to skip examples validation that we discussed.
There was a problem hiding this comment.
I believe your comment is wrong from my understanding. Having tests for xdoc examples, will not bring back examples into the javadoc. It was said it is going to be completely gutted instead.
There was a problem hiding this comment.
Maybe I need to rephrase. I meant that the list of modules to skip is there until the mentioned issue is done. After that, we drop this list and examples validation. Those two single-line comments are not a single sentence.
There was a problem hiding this comment.
After that, we drop this list and examples validation
There is nothing in #13100 that says the validation in a completely unrelated part will be gutted from this test.
There was a problem hiding this comment.
I have updated issue description.
There was a problem hiding this comment.
|
@stoyanK7 , is there any problematic review requests that you can not resolve easily ? |
romani
left a comment
There was a problem hiding this comment.
ok to merge.
this is good enough for first base implementation and we will definetely improve as we move more and more modules to templatization.
|
@rnveach please confirm you are satisfied with result of discussion at #13357 (comment) |
|
|
||
| <subsection name="Examples" id="Examples"> | ||
| <p> | ||
| <p id="Example1-config"> |
There was a problem hiding this comment.
Seems this is missing from #13357 (comment) and other things like changes to the example input file.
There was a problem hiding this comment.
It to generate link to examples, there is separate PR that allows link image popup for copy.
Very useful. @stoyanK7 , decided to do them from the beginning.
There was a problem hiding this comment.
You're right. I didn't add it there but explained it in #13357 (comment). Adding it in description too.
There was a problem hiding this comment.
Thanks. Is there a reason the macro doesn't create the ids itself so that we don't need to add them manually? Making sure we looked into it, but I guess it would put the link too far below the text it is connected to.
There was a problem hiding this comment.
As far as I'm aware, the macro would not be able to do this - edit a paragraph outside of its scope.
If we really want to automate it - I imagine some method that runs before the Xdoc generation and edits the templates. That method iterates through the macros, constructs an id based on parameters of the macro(Example2-code for example), and adds it to the paragraph preceding the macro.
There was a problem hiding this comment.
I was thinking more of adding the link to the end of the paragraph right where we start the scope. I am good regardless, it is just something to think about.
There was a problem hiding this comment.
Even if the paragraph is a whole screen-height long, the anchor will appear at the end of it, right above the example snippet. That's how the javascript that appends the anchors works.
Or am I misunderstanding you?
There was a problem hiding this comment.
Let's continue this discussion in separate issue, we can always improve in separate PR.
|
Semaphore restarted to let unstable job to pass. It was green before previous restart |
Resolves #13134
ExampleMacrothat works similar to SnippetMacroxdocs-examplesXdocTemplateParserthat is inspired by the default xdoc parser. The difference is that we only execute the macros, the rest of the file is kept the same. Good thing is that this parser will be reused for macros for the other generated content - properties, parent, etc..