[WFGP-292] Generate documentation for Galleon packs

provisioning/WFGP-292_doc_galleon-pack.adoc

@@ -0,0 +1,161 @@
+---
+categories:
+- wf-galleon
+- maven
+- user-experience
+stability-level: community
+issue: https://github.com/wildfly/wildfly-proposals/issues/738
+feature-team:
+ developer: jmesnil
+ sme:
+  - jfdenise
+  - ehsavoie
+ outside-perspective:
+  -
+---
+= Generate documentation for Galleon feature packs
+:author:            Jeff Mesnil
+:email:             jmesnil@redhat.com
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+| *_"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 ).
+
+== Overview
+
+At its core, WildFly is composed of extensions that provide management resources (grouped in subsystems and deployment resources).
+WildFly is providing a model reference for these resources at https://docs.wildfly.org/36/wildscribe/.
+
+Traditionally, this model reference was exhaustive and provided the full management capabilities of WildFly.
+It relied on its standalone-full-ha.xml configuration to provide it.
+
+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)
+
+We can improve the user experience for WildFly users by consolidating our tooling and providing consistent documentation for the WildFly ecosystem.
+
+Each feature pack should generate user documentation that describes the management capabilities offered by the feature pack in a user-friendly readable output.
+This user documentation should be made available in https://docs.wildfly.org/ or the web site that documents other feature packs.
+
+This documentation should be generated when the feature pack is built and made available as a companion to the feature pack. This should not required additional work from the feature pack developer other than providing correct information about their feature packs.
+
+=== User Stories
+
+* As a WildFly user, I want to have documentation of the capabilities and resources that are provided by any feature packs from WildFly community.
+* As a feature pack developer, I want to provide documentation for my feature pack that is automatically generated whenever I build my feature pack.
+
+== Issue Metadata
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/WFGP-292[WFGP-292 - Generate documentation for Feature Pack]
+
+=== 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
+* 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
+* 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.
+
+=== Relevant Installation Types
+
+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:
+** 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:
+** `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
+* 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. 
+
+=== Non-Requirements
+
+* the Look and Feel of the generated documenation is not configurable (it is based on wildscribe L&F).
+
+=== 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.
+
+== Implementation Plan
+
+=== Galleon
+
+* We might need to expose additional metadata for feature pack through the Galleon API (to be investigated).
+
+=== 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).
+
+=== 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:
+
+== Security Considerations
+
+This requirement provides documentation only.
+
+[[test_plan]]
+== Test Plan
+
+Tests will be added to the Galleon Maven plugin to verify that they are able to
+properly generate this documentation archive when the feature pack is built.
+
+== Community Documentation
+
+This feature will be documented in the Galleon Maven Plugin project and is meant to be read by feature pack developers.
+
+However once, this feature is delivered, it will have a high impact on community documentation as any of the feature pack provided by the WildFly community will be able to display this documentation (either in a standalone website, ususally on github.io, or aggregated in docs.wildfly.org).
+
+In particular, once this feature is delivered, it is recommended that feature pack developers review and check their documentation (model reference, metadata, etc.) to ensure that the information are correct, accurate and helpful.
+
+== Release Note Content
+
+Feature packs that are used to provision WildFly provide now generated documentation that describes the feature pack, its layers and the model references of the subsystems provided by the feature pack.