Rearchitecture the whole system
After having used that documentation system on two projects, I see some irremediable flaws :
- Starting a CDI system beside Maven-provided aether is kind of heavyweight (and can be replaced by the Java standard
ServcieLoader
mechanism). - Usage of asciidoctor-maven-plugin is a real pain. It generates enormous poms for which even the archetype mechanism is insufficient to relieve the pain.
- Relying upon a main class which loads the "architecture" is opposed to principles of this very project, which are to make sure simple things stay simple to do
As a consequence, I'm planning to rewrite the whole thing in a next version which will be a maven plugin (simpler to integrate in maven) which will run enhancers which are defined in its CLASSPATH (or by ServiceLoader) and which may even try to generate documents by invoking asciidoctor-maven-plugin with an ad-hoc configuration.
This is an important rewrite. As a consquence, I would like to get users feedback.
Do you think it's a good idea (reply with
For more precisions, take a look at this ADR template, and don't hesitate to suggest changes.
Effects on project
(only sections with real effects will be displayed here)
Functional Overview
- Architecture will be described using the structurizr
workspace.dsl
file, which is simpler to read/write than a java class. - Enhancers will be loaded from CLASSPATH (so users will have to add plugin dependencies to activate elements)
- Custom enhancers will be loaded from any supported scripting language, provided I find a way to load them)
All those changes are breaking compatibility with existing code
Quality Attributes
Execution should be faster, even more if I can find a way to integrate a correct asciidoctor configuration (or mixin)
Constraints
This is still maven only, and still generates pure HTML documents and revealjs presentations
Principles
IoC will use maven (poor) mechanism Custom classloading will use typical Groovy mechanisms
Software Architecture
Will be vastly impacted, as I'll have to write a plugin having more than one mojo, I think
Code
All code will be modified