This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch 2.x in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit cdae032ae47c15e8f7f875b35b81ef1d1a9bbbfb Author: Volkan Yazıcı <[email protected]> AuthorDate: Thu Feb 29 16:34:17 2024 +0100 Adapt the most recent docgen changes --- pom.xml | 36 ++++++++++++++-------- src/docgen-templates/interface.adoc.ftl | 3 +- src/docgen-templates/plugin.adoc.ftl | 54 ++++++++++++++++++++++++--------- src/docgen-templates/scalars.adoc.ftl | 4 +-- 4 files changed, 66 insertions(+), 31 deletions(-) diff --git a/pom.xml b/pom.xml index ce70851308..199fcd417b 100644 --- a/pom.xml +++ b/pom.xml @@ -334,7 +334,7 @@ <maven.site.deploy.skip>true</maven.site.deploy.skip> <!-- Dependency versions --> - <log4j-docgen.version>0.8.0-SNAPSHOT</log4j-docgen.version> + <log4j-docgen.version>1.0.0-SNAPSHOT</log4j-docgen.version> <!-- Versions of libraries whose plugin descriptors will be documented: --> <docgen.log4j.version>2.23.0-SNAPSHOT</docgen.log4j.version> @@ -873,7 +873,25 @@ <artifactId>log4j-docgen-maven-plugin</artifactId> <version>${log4j-docgen.version}</version> <inherited>false</inherited> + + <!-- Common docgen configuration --> + <configuration> + <descriptorFileMatchers> + <descriptorFileMatcher> + <baseDirectory>${project.build.directory}/plugin-descriptors</baseDirectory> + <pathPatterns>glob:**/*.xml</pathPatterns> + </descriptorFileMatcher> + </descriptorFileMatchers> + <typeFilter> + <excludes> + <exclude>java\..+</exclude> + </excludes> + </typeFilter> + </configuration> + <executions> + + <!-- Generate AsciiDoc from download plugin descriptors --> <execution> <id>generate-plugin-docs</id> <goals> @@ -881,12 +899,6 @@ </goals> <phase>pre-site</phase> <configuration> - <descriptorFileMatchers> - <descriptorFileMatcher> - <baseDirectory>${project.build.directory}/plugin-descriptors</baseDirectory> - <pathPatterns>glob:**/*.xml</pathPatterns> - </descriptorFileMatcher> - </descriptorFileMatchers> <templateDirectory>${project.basedir}/src/docgen-templates</templateDirectory> <scalarsTemplate> <source>scalars.adoc.ftl</source> @@ -902,6 +914,8 @@ </pluginTemplate> </configuration> </execution> + + <!-- Generate XSD from download plugin descriptors --> <execution> <id>generate-plugin-schema</id> <goals> @@ -909,16 +923,12 @@ </goals> <phase>pre-site</phase> <configuration> - <descriptorFileMatchers> - <descriptorFileMatcher> - <baseDirectory>${project.build.directory}/plugin-descriptors</baseDirectory> - <pathPatterns>glob:**/*.xml</pathPatterns> - </descriptorFileMatcher> - </descriptorFileMatchers> <schemaFile>${project.build.directory}/generated-sources/site/resources/config.xsd</schemaFile> </configuration> </execution> + </executions> + </plugin> <plugin> diff --git a/src/docgen-templates/interface.adoc.ftl b/src/docgen-templates/interface.adoc.ftl index 53020979e8..cfa565913c 100644 --- a/src/docgen-templates/interface.adoc.ftl +++ b/src/docgen-templates/interface.adoc.ftl @@ -35,5 +35,6 @@ ${type.description.text} == Known implementations <#list type.implementations as impl> -* xref:${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}] + <#assign implSourcedType = lookup[impl]/> +* xref:../../${implSourcedType.groupId}/${implSourcedType.artifactId}/${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}] </#list> diff --git a/src/docgen-templates/plugin.adoc.ftl b/src/docgen-templates/plugin.adoc.ftl index f7d54b461d..9e34731833 100644 --- a/src/docgen-templates/plugin.adoc.ftl +++ b/src/docgen-templates/plugin.adoc.ftl @@ -27,7 +27,7 @@ Class:: `${type.className}` <#if sourcedType.groupId?has_content && sourcedType.artifactId?has_content> Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}` -</#if>${(type.description.text)!'N/A'} +</#if>${(type.description.text)!} [#${type.className?replace('.', '_')}-XML-snippet] == XML snippet @@ -48,16 +48,16 @@ ${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(has_elements?th </#list> <#if has_elements> <#list type.elements as element> + <#assign multiplicitySuffix = (element.multiplicity == '*')?then('<!-- multiple occurrences allowed -->','')/> + <#assign elementName = 'a-' + element.type?keep_after_last('.') + '-implementation'/> <#if lookup[element.type]??> <#assign element_type = lookup[element.type].type/> <#-- @ftlvariable name="element_type" type="org.apache.logging.log4j.docgen.model.AbstractType" --> <#if element_type.name?? && !element_type.implementations?has_content> - <#-- @ftlvariable name="element_type" type="org.apache.logging.log4j.docgen.model.PluginType" --> - <${element_type.name}/> - <#else> - <a-${element.type?keep_after_last('.')}-implementation/><#if element.multiplicity == '*'><!-- multiple occurrences allowed --></#if> + <#assign elementName = element_type.name/> </#if> </#if> + <${elementName}/>${multiplicitySuffix} </#list> </${type.name}> </#if> @@ -68,17 +68,18 @@ ${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(has_elements?th [#${type.className?replace('.', '_')}-attributes] == Attributes -Required attributes are in **bold face**. +Optional attributes are denoted by `?`-suffixed types. [cols="1m,1m,1m,5"] |=== |Name|Type|Default|Description <#list type.attributes?sort_by('name') as attr> -|${attr.required?then('**', '')}${attr.name}${attr.required?then('**', '')} -|xref:../../scalars.adoc#${attr.type?replace('.', '_')}[${attr.type?contains('.')?then(attr.type?keep_after_last('.'), attr.type)}] + <#assign requirementSuffix = attr.required?then('', '?')/> +|${attr.name} +|xref:../../scalars.adoc#${attr.type?replace('.', '_')}[${attr.type?contains('.')?then(attr.type?keep_after_last('.'), attr.type)}]${requirementSuffix} |${attr.defaultValue!} -a|${(attr.description.text)!'N/A'} +a|${(attr.description.text)!} </#list> |=== @@ -88,19 +89,41 @@ a|${(attr.description.text)!'N/A'} [#${type.className?replace('.', '_')}-components] == Nested components -Required components are in **bold face**. +Optional components are denoted by `?`-suffixed types. [cols="1m,1m,5"] |=== |Tag|Type|Description <#list type.elements?sort_by('type') as element> + <#assign requirementSuffix = element.required?then('', '?')/> + <#assign descriptionCell = (element.description.text)!/> + <#assign elementName = element.type?contains('.')?then(element.type?keep_after_last('.'), element.type)/> <#if lookup[element.type]??> -|${element.required?then('**', '') + (lookup[element.type].type.name!'N/A') + element.required?then('**', '')} -|xref:${element.type}.adoc[${element.type?contains('.')?then(element.type?keep_after_last('.'), element.type)}] -a|${(element.description.text)!'N/A'} - + <#assign elementSourcedType = lookup[element.type]/> + <#assign elementType = elementSourcedType.type/> + <#assign tagCell = elementType.name!/> + <#switch elementType.class.simpleName> + <#case 'PluginType'> + <#case 'AbstractType'> +|${tagCell} +|xref:../../${elementSourcedType.groupId}/${elementSourcedType.artifactId}/${element.type}.adoc[${elementName}]${requirementSuffix} +a|${descriptionCell} + <#break> + <#case 'ScalarType'> +|${tagCell} +|xref:../scalars.adoc#${element.type?replace('.', '_')}[${elementName}]${requirementSuffix} +a|${descriptionCell} + <#break> + <#default> + <#stop 'Unknown type `' + element.type + '` modelled in class `' + elementType.class.name + '`'/> + </#switch> + <#else> +| +|${elementName}${requirementSuffix} +a|${descriptionCell} </#if> + </#list> |=== </#if> @@ -110,6 +133,7 @@ a|${(element.description.text)!'N/A'} == Known implementations <#list type.implementations as impl> -* xref:${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}] + <#assign implSourcedType = lookup[impl]/> +* xref:../../${implSourcedType.groupId}/${implSourcedType.artifactId}/${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}] </#list> </#if> diff --git a/src/docgen-templates/scalars.adoc.ftl b/src/docgen-templates/scalars.adoc.ftl index cb581261cc..9b5edb9add 100644 --- a/src/docgen-templates/scalars.adoc.ftl +++ b/src/docgen-templates/scalars.adoc.ftl @@ -32,14 +32,14 @@ Type converter plugins are used to convert simple `String` values into other typ Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}` </#if> -${scalar.description.text} +${(scalar.description.text)!} <#if scalar.values?size != 0> [#${scalar.className?replace('.', '_')}-values] === Possible values <#list scalar.values as value> -`${value.name}`:: ${(value.description.text)!'N/A'} +`${value.name}`:: ${(value.description.text)!} </#list> </#if> </#list>
