[wildfly-dev] Re: [proposal] Generate "javadoc-like" documentation for feature packs

Hi, Here is an update on that proposal[1] after your feedback (thanks!). I’ve a prototype of the RFE[2] that is good enough to give a broad idea of the finished feature. It is using a new documentation generator that supersedes WildScribe and use Qute for its template engine. The impact for feature pack developers is minimal, they will have to bump the galleon-plugins version and that’s it. To make it more visual, I applied the changes to WildFly itself and the diff is minimal[3] (including the changes to the doc module of WildFly & the removal of the Wildscribe dependency). WildFly is a special case as we want to have a single documentation entry point while we have 2 feature packs (wildfly-galleon-pack & wildfly-ee-galleon-pack). For this special case, we generates the documentation from the feature pack *and its dependencies*. For other feature packs, there will be nothing to do. I generated this doc and pushes it to my fork of docs.wildfly.org at https://jmesnil.github.io/wildfly.github.io/37/feature-pack/doc/reference/ [4] For reference, the existing doc is at https://docs.wildfly.org/37/wildscribe/index.html It’s not feature complete (log codes and capabilities are missing) but it’s good enough to give you an idea. In particular, it shows the following improvements: * All subsystems are described (eg microprofile-reactive-messaging-smallrye is missing in the current doc) * Each attribute and operations can display their raw DMR model in addition to the elements presented in the UI (that proves useful for complex attributes or operations). * There is some information that is not displayed by wildscribe (eg “alternatives") that is visible in the raw DMR model if we don’t want to surface it to the UI... * Current: https://docs.wildfly.org/37/wildscribe/subsystem/messaging-activemq/conne... * New https://jmesnil.github.io/wildfly.github.io/37/feature-pack/doc/reference... * most importantly, this doc comes for free for any feature pack (cloud, datasources, grpc, ai, etc.) As a part of this RFE, I also want to generate doc about the feature pack itself: https://jmesnil.github.io/wildfly.github.io/37/feature-pack/doc/index.html This offers interesting information such as: * the maven dependency to provision the feature pack * general information (description, licenses, source control) * layer information (including their dependencies, packages & properties) * that would complement or replace our handcrafted doc at https://docs.wildfly.org/37/Galleon_Guide.html#wildfly_layers & https://docs.wildfly.org/wildfly-galleon-feature-packs/#_support_for_wild... The feature pack doc needs a bit more polish but the generation of the model reference should soon be good enough to be usable. This would be part of a major bump of our Galleon plugins (there is plenty of major features coming up in them). I’ll finish the model reference to be on par (and above) with wildscribe. Please have a look at the output at [1] and provide any feedback to the proposal at [4].

Thanks, Jeff [1] https://github.com/jmesnil/wildfly-proposals/blob/WFGP-292_doc_galleon-pa... [2] https://github.com/jmesnil/galleon-plugins/tree/fp-metadata [3] https://github.com/wildfly/wildfly/compare/main...jmesnil:wildfly:feature... [4] https://jmesnil.github.io/wildfly.github.io/37/feature-pack/doc/reference/ -- Jeff Mesnil Engineer @ Red Hat http://jmesnil.net/ Unless otherwise stated above: Compagnie IBM France Siège Social : 17, avenue de l'Europe, 92275 Bois-Colombes Cedex RCS Nanterre 552 118 465 Forme Sociale : S.A.S. Capital Social : 664 614 175,50 € SIRET : 552 118 465 03644 - Code NAF 6203Z _______________________________________________ wildfly-dev mailing list -- wildfly-dev(a)lists.jboss.org To unsubscribe send an email to wildfly-dev-leave(a)lists.jboss.org Privacy Statement: https://www.redhat.com/en/about/privacy-policy List Archives: https://lists.jboss.org/archives/list/wildfly-dev@lists.jboss.org/message...