Skip to content

Commit cdae032

Browse files
vyvy
committed
Adapt the most recent docgen changes
1 parent c8d60bc commit cdae032

File tree

4 files changed

+66
-31
lines changed

4 files changed

+66
-31
lines changed

‎pom.xml

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -334,7 +334,7 @@
334334
<maven.site.deploy.skip>true</maven.site.deploy.skip>
335335

336336
<!-- Dependency versions -->
337-
<log4j-docgen.version>0.8.0-SNAPSHOT</log4j-docgen.version>
337+
<log4j-docgen.version>1.0.0-SNAPSHOT</log4j-docgen.version>
338338

339339
<!-- Versions of libraries whose plugin descriptors will be documented: -->
340340
<docgen.log4j.version>2.23.0-SNAPSHOT</docgen.log4j.version>
@@ -873,20 +873,32 @@
873873
<artifactId>log4j-docgen-maven-plugin</artifactId>
874874
<version>${log4j-docgen.version}</version>
875875
<inherited>false</inherited>
876+
877+
<!-- Common docgen configuration -->
878+
<configuration>
879+
<descriptorFileMatchers>
880+
<descriptorFileMatcher>
881+
<baseDirectory>${project.build.directory}/plugin-descriptors</baseDirectory>
882+
<pathPatterns>glob:**/*.xml</pathPatterns>
883+
</descriptorFileMatcher>
884+
</descriptorFileMatchers>
885+
<typeFilter>
886+
<excludes>
887+
<exclude>java\..+</exclude>
888+
</excludes>
889+
</typeFilter>
890+
</configuration>
891+
876892
<executions>
893+
894+
<!-- Generate AsciiDoc from download plugin descriptors -->
877895
<execution>
878896
<id>generate-plugin-docs</id>
879897
<goals>
880898
<goal>generate-documentation</goal>
881899
</goals>
882900
<phase>pre-site</phase>
883901
<configuration>
884-
<descriptorFileMatchers>
885-
<descriptorFileMatcher>
886-
<baseDirectory>${project.build.directory}/plugin-descriptors</baseDirectory>
887-
<pathPatterns>glob:**/*.xml</pathPatterns>
888-
</descriptorFileMatcher>
889-
</descriptorFileMatchers>
890902
<templateDirectory>${project.basedir}/src/docgen-templates</templateDirectory>
891903
<scalarsTemplate>
892904
<source>scalars.adoc.ftl</source>
@@ -902,23 +914,21 @@
902914
</pluginTemplate>
903915
</configuration>
904916
</execution>
917+
918+
<!-- Generate XSD from download plugin descriptors -->
905919
<execution>
906920
<id>generate-plugin-schema</id>
907921
<goals>
908922
<goal>generate-schema</goal>
909923
</goals>
910924
<phase>pre-site</phase>
911925
<configuration>
912-
<descriptorFileMatchers>
913-
<descriptorFileMatcher>
914-
<baseDirectory>${project.build.directory}/plugin-descriptors</baseDirectory>
915-
<pathPatterns>glob:**/*.xml</pathPatterns>
916-
</descriptorFileMatcher>
917-
</descriptorFileMatchers>
918926
<schemaFile>${project.build.directory}/generated-sources/site/resources/config.xsd</schemaFile>
919927
</configuration>
920928
</execution>
929+
921930
</executions>
931+
922932
</plugin>
923933

924934
<plugin>

‎src/docgen-templates/interface.adoc.ftl

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,6 @@ ${type.description.text}
3535
== Known implementations
3636

3737
<#list type.implementations as impl>
38-
* xref:${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
38+
<#assign implSourcedType = lookup[impl]/>
39+
* xref:../../${implSourcedType.groupId}/${implSourcedType.artifactId}/${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
3940
</#list>

‎src/docgen-templates/plugin.adoc.ftl

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Class:: `${type.className}`
2727
<#if sourcedType.groupId?has_content && sourcedType.artifactId?has_content>
2828
Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}`
2929

30-
</#if>${(type.description.text)!'N/A'}
30+
</#if>${(type.description.text)!}
3131

3232
[#${type.className?replace('.', '_')}-XML-snippet]
3333
== XML snippet
@@ -48,16 +48,16 @@ ${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(has_elements?th
4848
</#list>
4949
<#if has_elements>
5050
<#list type.elements as element>
51+
<#assign multiplicitySuffix = (element.multiplicity == '*')?then('<!-- multiple occurrences allowed -->','')/>
52+
<#assign elementName = 'a-' + element.type?keep_after_last('.') + '-implementation'/>
5153
<#if lookup[element.type]??>
5254
<#assign element_type = lookup[element.type].type/>
5355
<#-- @ftlvariable name="element_type" type="org.apache.logging.log4j.docgen.model.AbstractType" -->
5456
<#if element_type.name?? && !element_type.implementations?has_content>
55-
<#-- @ftlvariable name="element_type" type="org.apache.logging.log4j.docgen.model.PluginType" -->
56-
<${element_type.name}/>
57-
<#else>
58-
<a-${element.type?keep_after_last('.')}-implementation/><#if element.multiplicity == '*'><!-- multiple occurrences allowed --></#if>
57+
<#assign elementName = element_type.name/>
5958
</#if>
6059
</#if>
60+
<${elementName}/>${multiplicitySuffix}
6161
</#list>
6262
</${type.name}>
6363
</#if>
@@ -68,17 +68,18 @@ ${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(has_elements?th
6868
[#${type.className?replace('.', '_')}-attributes]
6969
== Attributes
7070

71-
Required attributes are in **bold face**.
71+
Optional attributes are denoted by `?`-suffixed types.
7272

7373
[cols="1m,1m,1m,5"]
7474
|===
7575
|Name|Type|Default|Description
7676

7777
<#list type.attributes?sort_by('name') as attr>
78-
|${attr.required?then('**', '')}${attr.name}${attr.required?then('**', '')}
79-
|xref:../../scalars.adoc#${attr.type?replace('.', '_')}[${attr.type?contains('.')?then(attr.type?keep_after_last('.'), attr.type)}]
78+
<#assign requirementSuffix = attr.required?then('', '?')/>
79+
|${attr.name}
80+
|xref:../../scalars.adoc#${attr.type?replace('.', '_')}[${attr.type?contains('.')?then(attr.type?keep_after_last('.'), attr.type)}]${requirementSuffix}
8081
|${attr.defaultValue!}
81-
a|${(attr.description.text)!'N/A'}
82+
a|${(attr.description.text)!}
8283

8384
</#list>
8485
|===
@@ -88,19 +89,41 @@ a|${(attr.description.text)!'N/A'}
8889
[#${type.className?replace('.', '_')}-components]
8990
== Nested components
9091

91-
Required components are in **bold face**.
92+
Optional components are denoted by `?`-suffixed types.
9293

9394
[cols="1m,1m,5"]
9495
|===
9596
|Tag|Type|Description
9697

9798
<#list type.elements?sort_by('type') as element>
99+
<#assign requirementSuffix = element.required?then('', '?')/>
100+
<#assign descriptionCell = (element.description.text)!/>
101+
<#assign elementName = element.type?contains('.')?then(element.type?keep_after_last('.'), element.type)/>
98102
<#if lookup[element.type]??>
99-
|${element.required?then('**', '') + (lookup[element.type].type.name!'N/A') + element.required?then('**', '')}
100-
|xref:${element.type}.adoc[${element.type?contains('.')?then(element.type?keep_after_last('.'), element.type)}]
101-
a|${(element.description.text)!'N/A'}
102-
103+
<#assign elementSourcedType = lookup[element.type]/>
104+
<#assign elementType = elementSourcedType.type/>
105+
<#assign tagCell = elementType.name!/>
106+
<#switch elementType.class.simpleName>
107+
<#case 'PluginType'>
108+
<#case 'AbstractType'>
109+
|${tagCell}
110+
|xref:../../${elementSourcedType.groupId}/${elementSourcedType.artifactId}/${element.type}.adoc[${elementName}]${requirementSuffix}
111+
a|${descriptionCell}
112+
<#break>
113+
<#case 'ScalarType'>
114+
|${tagCell}
115+
|xref:../scalars.adoc#${element.type?replace('.', '_')}[${elementName}]${requirementSuffix}
116+
a|${descriptionCell}
117+
<#break>
118+
<#default>
119+
<#stop 'Unknown type `' + element.type + '` modelled in class `' + elementType.class.name + '`'/>
120+
</#switch>
121+
<#else>
122+
|
123+
|${elementName}${requirementSuffix}
124+
a|${descriptionCell}
103125
</#if>
126+
104127
</#list>
105128
|===
106129
</#if>
@@ -110,6 +133,7 @@ a|${(element.description.text)!'N/A'}
110133
== Known implementations
111134

112135
<#list type.implementations as impl>
113-
* xref:${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
136+
<#assign implSourcedType = lookup[impl]/>
137+
* xref:../../${implSourcedType.groupId}/${implSourcedType.artifactId}/${impl}.adoc[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
114138
</#list>
115139
</#if>

‎src/docgen-templates/scalars.adoc.ftl

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,14 +32,14 @@ Type converter plugins are used to convert simple `String` values into other typ
3232
Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}`
3333
</#if>
3434

35-
${scalar.description.text}
35+
${(scalar.description.text)!}
3636
<#if scalar.values?size != 0>
3737

3838
[#${scalar.className?replace('.', '_')}-values]
3939
=== Possible values
4040

4141
<#list scalar.values as value>
42-
`${value.name}`:: ${(value.description.text)!'N/A'}
42+
`${value.name}`:: ${(value.description.text)!}
4343
</#list>
4444
</#if>
4545
</#list>

0 commit comments

Comments
 (0)