pathList - a {@code java.util.List} containing {@link PathWithAttribute} objects. (The script is
* free to modify and return this list.)
*
substitutor - a {@link StrSubstitutor} that can be used to look up variables embedded in the base
- * dir or other properties
- *
statusLogger - the {@link StatusLogger} that can be used to log events during script execution
+ * dir or other properties
+ *
statusLogger - the {@link StatusLogger} that can be used to log events during script execution
*
any properties declared in the configuration
*
* @param configuration the configuration
diff --git a/pom.xml b/pom.xml
index adb5cf93ecd..5dffdfa9955 100644
--- a/pom.xml
+++ b/pom.xml
@@ -331,18 +331,27 @@
======================== -->
- all,-missing,-html
+ We also don't generate Javadoc HTML for all modules, but only for two modules: `log4j-api` and `log4j-core`.
+ Hence, we disable it by default: -->
true
-
+ all,-missing,-html
+
truetrue
-
- 0|[1-9]\d*)\.(?0|[1-9]\d*)\.(?(0|[1-9]\d*)(-[a-zA-Z][0-9a-zA-Z-]*)?)$]]>
+
+ 0.8.0
+
+
+
+ ^java\..+
+
+ ${maven.multiModuleProjectDirectory}/target/plugin-descriptors/phase1
+ ${maven.multiModuleProjectDirectory}/target/plugin-descriptors/phase2
@@ -603,6 +612,7 @@
**/rabbitmq.config**/MANIFEST.MF.surefire-*
+ **/.log4j-*
@@ -682,6 +692,7 @@
org.apache.maven.pluginsmaven-resources-plugin
+
copy-site
@@ -725,6 +737,7 @@
+
copy-javadoc
@@ -733,10 +746,10 @@
site
- ${javadoc.skip}
+ ${maven.javadoc.skip}${maven.multiModuleProjectDirectory}/target/site/javadoc/${project.artifactId}
@@ -744,6 +757,7 @@
+
@@ -769,9 +783,95 @@
+
+
+ org.apache.logging.log4j
+ log4j-docgen-maven-plugin
+ ${log4j-docgen.version}
+ false
+
+
+
+
+
+
+
+ ${log4j.docgen.pluginDescriptorsDir.phase1}
+
+
+ ${log4j.docgen.pluginDescriptorsDir.phase2}
+
+
+
+
+
+ ${log4j.docgen.typeFilter.excludePattern}
+
+
+
+
+
+
+
+
+
+ generate-plugin-docs
+
+ generate-documentation
+
+ pre-site
+
+ ${project.basedir}/src/template/docgen
+
+ index.adoc.ftl
+ ${project.build.directory}/generated-sources/site/asciidoc/plugin-reference.adoc
+
+
+ type.adoc.ftl
+ ${project.build.directory}/generated-sources/site/asciidoc/_plugin-reference/%g-%a-%c.adoc
+
+
+
+
+
+
+ generate-plugin-schema
+
+ generate-schema
+
+ pre-site
+
+ ${project.version}
+ ${project.build.directory}/log4j-config.xsd
+
+
+
+
+
+
+
org.asciidoctorasciidoctor-maven-plugin
+
+ 3.0.0false
@@ -779,6 +879,19 @@
spring-asciidoctor-extensions-block-switch0.6.3
+
+
+ org.asciidoctor
+ asciidoctorj
+ 3.0.0-alpha.2
+
+
+ org.apache.logging.log4j
+ log4j-docgen-asciidoctor-extension
+ ${log4j-docgen.version}
+
@@ -793,11 +906,14 @@
target/sitetrue
- src/asciidoc/templates
+ src/template/asciidoctorrougeleft
+ ${project.build.directory}/plugin-descriptors
+ ${log4j.docgen.typeFilter.excludePattern}
+
diff --git a/src/changelog/.3.x.x/add_plugin_reference.xml b/src/changelog/.3.x.x/add_plugin_reference.xml
new file mode 100644
index 00000000000..47618da7334
--- /dev/null
+++ b/src/changelog/.3.x.x/add_plugin_reference.xml
@@ -0,0 +1,9 @@
+
+
+
+ Add _"Plugin Reference"_ to the website.
+It is a Javadoc-on-steroids focusing on Log4j plugins.
+
diff --git a/src/site/asciidoc/plugin-reference.adoc b/src/site/asciidoc/plugin-reference.adoc
new file mode 100644
index 00000000000..f41b0bbfbaa
--- /dev/null
+++ b/src/site/asciidoc/plugin-reference.adoc
@@ -0,0 +1,22 @@
+// vim: set syn=markdown :
+
+////
+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
+
+ http://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.
+////
+= Plugin reference
+
+This file is a stub.
+Its content will be auto-generated during build.
diff --git a/src/asciidoc/templates/document.html.erb b/src/template/asciidoctor/document.html.erb
similarity index 99%
rename from src/asciidoc/templates/document.html.erb
rename to src/template/asciidoctor/document.html.erb
index 36d13b0bb8b..3f0e34d84d4 100644
--- a/src/asciidoc/templates/document.html.erb
+++ b/src/template/asciidoctor/document.html.erb
@@ -69,6 +69,7 @@
diff --git a/src/template/docgen/index.adoc.ftl b/src/template/docgen/index.adoc.ftl
new file mode 100644
index 00000000000..9dc1d8c733c
--- /dev/null
+++ b/src/template/docgen/index.adoc.ftl
@@ -0,0 +1,59 @@
+<#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="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" -->
+
+= Plugin reference
+
+This page is a Javadoc-on-steroids specialized for Log4j plugins.
+This reference manual is derived from the source code of all Log4j plugins and types associated with them.
+You can use this reference manual to precisely customize your `log4j2.xml`.
+
+[INFO]
+====
+Every running Log4j system is a constellation of xref:../manual/plugins.adoc[plugins], which is analogous to beans in Java EE and Spring.
+This not only allows Log4j itself to be developed in individual components, but also enables extensibility users can leverage.
+====
+
+[#shortcuts]
+== Shortcuts
+
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Configuration[The `` element assembly in a `log4j2.xml`]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Appender[The type hierarchy of *appenders*]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Layout[The type hierarchy of *layouts*]
+* xref:#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Filter[The type hierarchy of *filters*]
+
+[#index]
+== Index
+
+Below is a list of all types reachable by plugins grouped by the Maven coordinate of the artifact bundling them.
+
+<#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/>
+
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}]
+=== `${sourcedType.groupId}:${sourcedType.artifactId}`
+
+
+include::_plugin-reference/${sourcedType.groupId}-${sourcedType.artifactId}-${sourcedType.type.className}.adoc[leveloffset=+4]
+
diff --git a/src/template/docgen/type.adoc.ftl b/src/template/docgen/type.adoc.ftl
new file mode 100644
index 00000000000..48f8dc24781
--- /dev/null
+++ b/src/template/docgen/type.adoc.ftl
@@ -0,0 +1,133 @@
+<#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.Type" -->
+<#-- @ftlvariable name="lookup" type="org.apache.logging.log4j.docgen.generator.TypeLookup" -->
+
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}]
+= ${type.name!('`' + type.className + '`')}
+
+Class:: `${type.className}`
+Provider:: `${sourcedType.groupId}:${sourcedType.artifactId}`
+
+${(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" -->
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}_XML-snippet]
+== XML snippet
+[source, xml]
+----
+ <#assign tag><${type.name}
+ <#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(hasElements?then('>', '/>'), '')}
+ <#else>
+${indent}${attr.name}="${attr.defaultValue!}"${attr?is_last?then(hasElements?then('>', '/>'), '')}
+
+
+ <#if hasElements>
+ <#list type.elements as element>
+ <#assign multiplicitySuffix = (element.multiplicity == '*')?then('','')/>
+ <#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/>
+
+
+ <${elementName}/>${multiplicitySuffix}
+
+
+
+
+----
+
+<#if type.attributes?has_content>
+
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}-attributes]
+== Attributes
+
+Optional attributes are denoted by `?`-suffixed types.
+
+[cols="1m,1m,1m,5"]
+|===
+|Name|Type|Default|Description
+
+ <#list type.attributes?sort_by('name') as attr>
+ <#assign requirementSuffix = attr.required?then('', '?')/>
+|${attr.name}
+ <#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?replace('.', '-')}_${attrSourcedType.artifactId?replace('.', '-')}_${attr.type?replace('.', '-')}[${attrTypeName}]${requirementSuffix}
+ <#else>
+|${attrTypeName}${requirementSuffix}
+
+|${attr.defaultValue!}
+a|${(attr.description.text)!}
+
+
+|===
+
+<#if hasElements>
+
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}_components]
+== Nested components
+
+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]??>
+ <#assign elementSourcedType = lookup[element.type]/>
+ <#assign tagCell = elementSourcedType.type.name!/>
+|${tagCell}
+|xref:#${elementSourcedType.groupId?replace('.', '-')}_${elementSourcedType.artifactId?replace('.', '-')}_${element.type?replace('.', '-')}[${elementName}]${requirementSuffix}
+ <#else>
+|
+|${elementName}${requirementSuffix}
+
+a|${descriptionCell}
+
+
+|===
+
+<#if type.implementations?has_content>
+
+[#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${type.className?replace('.', '-')}_implementations]
+== Known implementations
+
+ <#list type.implementations as impl>
+ <#assign implSourcedType = lookup[impl]/>
+* xref:#${implSourcedType.groupId?replace('.', '-')}_${implSourcedType.artifactId?replace('.', '-')}_${impl?replace('.', '-')}[${impl?contains('.')?then(impl?keep_after_last('.'), impl)}]
+
+