This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch 2.x-docgen in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 150b5bb1825db50a049d8904b3da890bd863dfd7 Author: Volkan Yazıcı <[email protected]> AuthorDate: Wed Mar 6 21:43:06 2024 +0100 Adapt most recent `log4j-docgen` changes --- pom.xml | 18 ++--- .../{scalars.adoc.ftl => index.adoc.ftl} | 37 ++++----- src/docgen-templates/interface.adoc.ftl | 40 ---------- src/docgen-templates/license.adoc.ftl | 16 ++++ .../{plugin.adoc.ftl => type.adoc.ftl} | 90 +++++++++++----------- 5 files changed, 81 insertions(+), 120 deletions(-) diff --git a/pom.xml b/pom.xml index 199fcd417b..feb520e4a4 100644 --- a/pom.xml +++ b/pom.xml @@ -900,18 +900,14 @@ <phase>pre-site</phase> <configuration> <templateDirectory>${project.basedir}/src/docgen-templates</templateDirectory> - <scalarsTemplate> - <source>scalars.adoc.ftl</source> - <target>${project.build.directory}/generated-sources/site/asciidoc/plugin-reference/scalars.adoc</target> - </scalarsTemplate> - <interfaceTemplate> - <source>interface.adoc.ftl</source> + <indexTemplate> + <source>index.adoc.ftl</source> + <target>${project.build.directory}/generated-sources/site/asciidoc/plugin-reference.adoc</target> + </indexTemplate> + <typeTemplate> + <source>type.adoc.ftl</source> <target>${project.build.directory}/generated-sources/site/asciidoc/plugin-reference/%g/%a/%c.adoc</target> - </interfaceTemplate> - <pluginTemplate> - <source>plugin.adoc.ftl</source> - <target>${project.build.directory}/generated-sources/site/asciidoc/plugin-reference/%g/%a/%c.adoc</target> - </pluginTemplate> + </typeTemplate> </configuration> </execution> diff --git a/src/docgen-templates/scalars.adoc.ftl b/src/docgen-templates/index.adoc.ftl similarity index 55% rename from src/docgen-templates/scalars.adoc.ftl rename to src/docgen-templates/index.adoc.ftl index 9b5edb9add..496ac6ce68 100644 --- a/src/docgen-templates/scalars.adoc.ftl +++ b/src/docgen-templates/index.adoc.ftl @@ -15,31 +15,22 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> -<#-- @ftlvariable name="sourcedTypes" type="org.apache.logging.log4j.docgen.generator.ArtifactSourcedType[]" --> +<#-- @ftlvariable name="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" --> <#include "license.adoc.ftl"> -[#type-converters] -= Type converters - -Type converter plugins are used to convert simple `String` values into other types. -<#list sourcedTypes as sourcedType> -<#assign scalar = sourcedType.type/> -<#-- @ftlvariable name="scalar" type="org.apache.logging.log4j.docgen.model.ScalarType" --> - -[#${scalar.className?replace('.', '_')}] -== `${scalar.className}` - - <#if sourcedType.groupId?has_content && sourcedType.artifactId?has_content> -Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}` - </#if> - -${(scalar.description.text)!} - <#if scalar.values?size != 0> +[#index] += Index +<#assign sourcedTypes = lookup?values/> +<#-- @ftlvariable name="sourcedTypes" type="org.apache.logging.log4j.docgen.generator.ArtifactSourcedType[]" --> +<#assign lastGroupId = ''/> +<#assign lastArtifactId = ''/> +<#list sourcedTypes?sort_by('artifactId', 'groupId', ['type', 'className']) as sourcedType> + <#if sourcedType.groupId != lastGroupId || sourcedType.artifactId != lastArtifactId> + <#assign lastGroupId = sourcedType.groupId/> + <#assign lastArtifactId = sourcedType.artifactId/> -[#${scalar.className?replace('.', '_')}-values] -=== Possible values +[#${sourcedType.groupId?replace('.', '_')}-${sourcedType.artifactId?replace('.', '_')}] +== `${sourcedType.groupId}:${sourcedType.artifactId}` - <#list scalar.values as value> -`${value.name}`:: ${(value.description.text)!} - </#list> </#if> +* xref:plugin-reference/${sourcedType.groupId}/${sourcedType.artifactId}/${sourcedType.type.className}.adoc[`${sourcedType.type.className}`] </#list> diff --git a/src/docgen-templates/interface.adoc.ftl b/src/docgen-templates/interface.adoc.ftl deleted file mode 100644 index cfa565913c..0000000000 --- a/src/docgen-templates/interface.adoc.ftl +++ /dev/null @@ -1,40 +0,0 @@ -<#ftl output_format="plainText" strip_whitespace=true> -<#-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<#-- @ftlvariable name="sourcedType" type="org.apache.logging.log4j.docgen.model.ArtifactSourcedType" --> -<#assign type = sourcedType.type/> -<#-- @ftlvariable name="type" type="org.apache.logging.log4j.docgen.model.AbstractType" --> -<#-- @ftlvariable name="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" --> -<#include "license.adoc.ftl"> -[#${type.className?replace('.', '_')}] -= ${type.className?keep_after_last('.')} - -Class:: `${type.className}` -<#if sourcedType.groupId?has_content && sourcedType.artifactId?has_content> -Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}` - -</#if><#if type.description??> -${type.description.text} -</#if> - -[#${type.className?replace('.', '_')}-implementations] -== Known implementations - -<#list type.implementations as 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/license.adoc.ftl b/src/docgen-templates/license.adoc.ftl new file mode 100644 index 0000000000..797f7c9fb7 --- /dev/null +++ b/src/docgen-templates/license.adoc.ftl @@ -0,0 +1,16 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +//// diff --git a/src/docgen-templates/plugin.adoc.ftl b/src/docgen-templates/type.adoc.ftl similarity index 63% rename from src/docgen-templates/plugin.adoc.ftl rename to src/docgen-templates/type.adoc.ftl index 8085461a2b..49f96edf17 100644 --- a/src/docgen-templates/plugin.adoc.ftl +++ b/src/docgen-templates/type.adoc.ftl @@ -17,52 +17,58 @@ --> <#-- @ftlvariable name="sourcedType" type="org.apache.logging.log4j.docgen.model.ArtifactSourcedType" --> <#assign type = sourcedType.type/> -<#-- @ftlvariable name="type" type="org.apache.logging.log4j.docgen.PluginType" --> +<#-- @ftlvariable name="type" type="org.apache.logging.log4j.docgen.Type" --> <#-- @ftlvariable name="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" --> <#include "license.adoc.ftl"> + [#${type.className?replace('.', '_')}] -= ${type.name} += ${type.name!('`' + type.className + '`')} Class:: `${type.className}` <#if sourcedType.groupId?has_content && sourcedType.artifactId?has_content> Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}` -</#if>${(type.description.text)!} +</#if> + +${(type.description.text)!} +<#assign hasElements = ((type.elements?size)!0) != 0/> +<#if type.class.simpleName == 'PluginType'> + <#-- @ftlvariable name="type" type="org.apache.logging.log4j.docgen.PluginType" --> [#${type.className?replace('.', '_')}-XML-snippet] == XML snippet [source, xml] ---- -<#assign tag><${type.name} </#assign> -<#assign indent = tag?replace('.', ' ', 'r')/> -<#assign has_elements = type.elements?size != 0/> -<#if !type.attributes?has_content> + <#assign tag><${type.name} </#assign> + <#assign indent = tag?replace('.', ' ', 'r')/> + <#if !type.attributes?has_content> <${type.name}/> - <#else> - <#list type.attributes?sort_by('name') as attr> - <#if attr?is_first> -${tag}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(has_elements?then('>', '/>'), '')} - <#else> -${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(has_elements?then('>', '/>'), '')} - </#if> - </#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> - <#assign elementName = element_type.name/> - </#if> + <#else> + <#list type.attributes?sort_by('name') as attr> + <#if attr?is_first> +${tag}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(hasElements?then('>', '/>'), '')} + <#else> +${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(hasElements?then('>', '/>'), '')} </#if> - <${elementName}/>${multiplicitySuffix} </#list> + <#if hasElements> + <#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> + <#assign elementName = element_type.name/> + </#if> + </#if> + <${elementName}/>${multiplicitySuffix} + </#list> </${type.name}> - </#if> -</#if> + </#if> + </#if> ---- +</#if> <#if type.attributes?has_content> [#${type.className?replace('.', '_')}-attributes] @@ -77,14 +83,20 @@ Optional attributes are denoted by `?`-suffixed types. <#list type.attributes?sort_by('name') as attr> <#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} + <#assign attrTypeName = attr.type?contains('.')?then(attr.type?keep_after_last('.'), attr.type)/> + <#if lookup[attr.type]??> + <#assign attrSourcedType = lookup[attr.type]/> +|xref:../../${attrSourcedType.groupId}/${attrSourcedType.artifactId}/${attr.type}.adoc[${attrTypeName}]${requirementSuffix} + <#else> +|${attrTypeName}${requirementSuffix} + </#if> |${attr.defaultValue!} a|${(attr.description.text)!} </#list> |=== </#if> -<#if has_elements> +<#if hasElements> [#${type.className?replace('.', '_')}-components] == Nested components @@ -101,28 +113,14 @@ Optional components are denoted by `?`-suffixed types. <#assign elementName = element.type?contains('.')?then(element.type?keep_after_last('.'), element.type)/> <#if lookup[element.type]??> <#assign elementSourcedType = lookup[element.type]/> - <#assign elementType = elementSourcedType.type/> - <#assign tagCell = elementType.name!/> - <#switch elementType.class.simpleName> - <#case 'PluginType'> - <#case 'AbstractType'> + <#assign tagCell = elementSourcedType.type.name!/> |${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> +a|${descriptionCell} </#list> |===
