Update proposal based on feedback

Signed-off-by: Jeff Mesnil <jmesnil@ibm.com>

Author: jmesnil

provisioning/WFGP-292_doc_galleon-pack.adoc

@@ -15,16 +15,16 @@ feature-team:
 ---
 = Generate documentation for Galleon feature packs
 :author:            Jeff Mesnil
-:email:             jmesnil@redhat.com
+:email:             jmesnil@ibm.com
 :toc:               left
 :icons:             font
 :idprefix:
 :idseparator:       -
 
-| *_"Javadoc" for feature packs_*
+*_"Javadoc" for feature packs_*
 
 The goal of that proposal is to provide documentation of the capabilities and resources that are provided by WildFly and its ecosystem of Galleon feature packs.
-This documentation is self-contained and automatically generated when the featuer pack are built ).
+This documentation is self-contained and automatically generated when the feature packs are built.
 
 == Overview
 
@@ -38,8 +38,8 @@ However, over time, this approach has shown some cracks:
 
 * Some new subsystems are provided by other configurations (e.g. standalone-microprofile.xml). This was worked around by adding additional extensions when the model referenced is generated (in WildFly's `docs` module) but is out of sync.
 * WildFly is now composed of 2 Galleon packs (wildfly-ee-galleon-pack & wildfly-galleon-pack). Each Galleon pack provides different extensions and resources but this is not clear from the management model (e.g. which Galleon pack provides the `microprofile-config-smallrye` subsystem?)
-* Additional capabilities for WildFly are provided by other feature packs (mvc-krazo, grpc, wildfly-preview, etc.) that do not provide their model references and makes it more difficult for the users to understand which resources, attributes and operations are available to configure their installations. They have to rely on jboss-cli to get the information and while it is available, it does not make it very user friendly.
-* More generally, the tool that is used to generate this model reference (wildscribe) is lagging behind new WildFly management features (stability level was added recently while it’s been in WildFly for some time)
+* Additional capabilities for WildFly are provided by other feature packs (mvc-krazo, grpc, wildfly-preview, etc.) that do not provide their model references and makes it more difficult for the users to understand which resources, attributes and operations are available to configure their installations. They have to rely on jboss-cli to get the information and while it is available, it does not make it very user-friendly.
+* More generally, the tool that is used to generate this model reference (wildscribe) is lagging behind new WildFly management features (stability level was added recently while it's been in WildFly for some time)
 
 We can improve the user experience for WildFly users by consolidating our tooling and providing consistent documentation for the WildFly ecosystem.
 
@@ -62,18 +62,19 @@ This documentation should be generated when the feature pack is built and made a
 === Affected Projects or Components
 
 * WildFly Galleon Plugins - https://github.com/wildfly/galleon-plugins
-** Add a `doc` goal to the maven plugin to generate a companion doc archive next to the feature pack itself
+** Generate documentation when the `build-feature-pack` goal is invoked. It generates a companion doc archive next to the feature pack itself
 * Galleon - https://github.com/wildfly/galleon
 ** Might be impacted if we are missing any metadata from the feature pack to generate its documentation
 * Wildscribe - https://github.com/wildfly/wildscribe
-** Reuse its site-generator to generate the Model reference of the feature packs
+** This RFE would be a full replacement of Wildscribe that would be archived.
 * Any project publishing feature packs (wildfly, grpc-feature-pack, ai-feature-pack, etc.)
 ** They will be updated to bump the version of the Galleon maven plugin
-** They will have to execute the `doc` goal, *in addition to the `build-feature-pack` goal*
 ** *No other changes should be required*
 * WildFly - https://github.com/wildfly/
-** Its model references will be generated when its feature packs are built. The dependency to wildscribe from its docs module will be removed 
-** WildFly release process will have to be updated so that its model reference is published to https://docs.wildfly.org/ based on this new doc archive instead of the model reference generated by wildfly docs module.
+** Its model references will be generated when its feature packs are built.
+*** For WildFly, we could generate a single documentation entry points that would document the wildfly-galleon-pack and also the capabilites coming from the wildfly-ee-galleon-pack.
+** The dependency to wildscribe from its docs module will be removed and replaced by unarchiving the documentation when the  wildfly-galleon-pack feature pack is built.
+** There would be no changes to the WildFly release process.
 
 === Relevant Installation Types
 
@@ -82,29 +83,35 @@ This requirement does not impact installation types.
 == Requirements
 
 
-* When the `doc` goal of the `org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin` is invoked (i.e. when the feature pack is built), generate a `doc.zip` archive that contains:
+* When the `build-feature-pack` goal of the `org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin` is invoked (i.e. when the feature pack is built), generate a `-doc.zip` archive that contains:
 ** human-readable HTML documention of the feature pack stored in a `doc` directory. This documentation includes:
 *** the Model reference of the resources provided by the feature pack (in a format similar to the existing https://docs.wildfly.org/36/wildscribe/[WildFly model reference])
 *** the log messages that can be displayed by the feature pack (in a format similar to the existing https://docs.wildfly.org/36/wildscribe/log-message-reference.html[WildFly log messages])
-** the model reference of the resources provided by the feature pack (stored in a DMR representation in a JSON file) - generated during the `build-feature-pack` goal and stored in a `META-INF/model.json` file
-** the metadata of the feature pack (stored in a JSON file) - generated during the `build-feature-pack` goal and stored in a `META-INF/metadata.json` file
-* This companion doc.zip is attached to the feature pack's Maven model with the coordinates:
+** the model reference of the resources provided by the feature pack (stored in a JSON file containing the DMR representation) - generated during the `build-feature-pack` goal and stored in a `META-INF/model.json` file
+** the metadata of the feature pack (stored in a JSON file) - generated during the `build-feature-pack` goal and stored in a `META-INF/metadata.json` file. Information provided by these metada includes:
+*** General information on the feature pack (name, description, scm, licenses)
+*** Layers (including their depencencies, packages and properties)
+* This companion doc.zip is attached to the feature pack's Maven module (`<project>`) with the coordinates:
 ** `groupId` - same as the feature pack
 ** `artifactId` - same as the feature pack
 ** `version` - same as the feature pack
 ** `classifier` - `doc`
 ** `extension` - `zip`
 * When the feature pack is installed or published, this companion doc.zip is also installed and published
+** This new artifact would be signed during publication (as is the feature pack itself)
 * Other tools that wants to leverage this documentation artifacts must not expect they are always availavle alongside the feature pack. It will only exist when feature packs project are upgraded to the Galleon Maven plugin that provides this feature. 
+* The generated documentation will uses information from the feature pack's pom.xml (description, scm, licenses, etc.)
 
 === Non-Requirements
 
-* the Look and Feel of the generated documenation is not configurable (it is based on wildscribe L&F).
+* the Look and Feel of the generated documenation is not configurable.
 
 === Future Work
 
 * This documentation archive can be leveraged by other tools to provide an extensive and exhaustive documentation for all feature packs provided by the WildFly community
 * We might consider adding the documentation of the feature packs that are used to provision a WildFly installation *inside* the installation itself.
+* We could build a searchable index of the documentation (to improve its accessibility).
+ There is also work on a https://github.com/model-graph-tools[Graph representation of the WildFly management model] that could enhance the documentation experience
 
 == Implementation Plan
 
@@ -114,29 +121,25 @@ This requirement does not impact installation types.
 
 === Wildscribe
 
-* Modify wildscribe's site-generator so that it can read the DMR output of a `:read-resource-description` from a JSON file (in addition to read it from a DMR file).
+* Archive the project.
 
 === Galleon Maven Plug-in
 
-. When the `build-feature-pack` goal of the `org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin` is invoked (ie when the feature pack is built):
-.. generate the model reference of the feature pack by executing `:read-resource-description` operation(s)
-on the server provisioned by the plugin (that only contains the resources provided by the feature pack)/
-.. Store that model in a JSON file, `model.json`
-.. Generate and store feature pack metadata in a `metadata.json`
-** this metadata includes data coming from the feature pack itself (eg its layers and their dependencies) and the `pom.xml` (project url, description, licenses, etc.)
-. When the `doc` goal of the `org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin` is invoked:
-.. Generate human-readable documentation based on the feature pack model.json and metadata.json files
-** Model reference is generated by delegating it to wildscribe's site-generator.
-*** We will have to filter out the descriptions of resources that do not belong to the feature pack that is built (e.g. `path`, `socket-binding`) or filter in the `/subsystem` and `/deployment` substrees only.
-** Log messages are extracted from the provisioned server's JBoss modules
-*** This code in wildscribe might have to be updated to ensure that we only keep the log messages for the JBoss modules brought by the feature pack that is built.
-.. Create a `doc.zip` archive that contains:
-** `META-INF/model.json` - the Model reference (stored in a DMR format in a JSON file)
-** `META-INF/metadata.json` - the feature pack metadata
-** `doc/` - Generated HTML documentation about the feature pack. In particular:
-*** `doc/index.html` - Home page of the feature pack documentation
-*** `doc/reference/index.html` - Home page of the model reference of the feature pack
-.. Attach this `doc.zip` archive` to the Maven project:
+When the `build-feature-pack` goal of the `org.wildfly.galleon-plugins:wildfly-galleon-maven-plugin` is invoked (ie when the feature pack is built):
+
+. generate the model reference of the feature pack by executing `:read-resource-description` operation on the server provisioned by the plugin (that only contains the resources provided by the feature pack)
+. Store that model in a JSON file, `model.json`
+. Generate and store feature pack metadata in a `metadata.json`
+. Generate human-readable documentation based on the feature pack model.json and metadata.json files
+* Model reference is generated by delegating it to a dedicated `doc-gen` Maven project (that does not depend on Maven plugin API)
+* Log messages are extracted from the provisioned server's JBoss modules
+. Create a `-doc.zip` archive that contains:
+* `META-INF/model.json` - the Model reference (stored in a DMR format in a JSON file)
+* `META-INF/metadata.json` - the feature pack metadata
+* `doc/` - Generated HTML documentation about the feature pack. In particular:
+** `doc/index.html` - Home page of the feature pack documentation
+** `doc/reference/index.html` - Home page of the model reference of the feature pack
+. Attach this `-doc.zip` archive to the Maven project.
 
 == Security Considerations