Is your feature request related to a problem? Please describe.
Currently both knotx project and it's documentation are highly fragmented. It could benefit from a single document that would explain how a single request is processed by knotx. I would like to base such documentation on existing sample projects, specifically https://github.com/Knotx/knotx-example-project/tree/master/template-processing/handlebars
Describe the solution you'd like
Let's assume we would like to document the flow for template engine.
There are four main stages of request processing (repository step, fragment splitter, fragment handler, fragment assembler).
I would like to visualize each one of them as a separate column with blocks representing relevant classes involved in the processing. For each block I'd like to see:
class name
github source link
configuration information (link to relevant .conf file on github)
input information (for connector - incoming request, for splitter - html, for fragments handler - array of Fragments and so on)
output information (for connector - html string, for splitter - list of Fragments and so on).
I would like to include all relevant data for at list single test scenario. That means I would like to be able to expand list of Fragments and examine a JSON representation of each one of them - same as during debug of a deployed application.
If a certain stage has more classes involved in the processing (for Fragment Handler it would be Fragment Engine, Task Engine etc) additional blocks can be added further down in the column representing given stage.
I would also like to see how OpenApi is configured (openapi.yaml) and how config files from knotx-stack are referenced in project-specific files (in this case operations.conf from knotx-example-project).
Describe alternatives you've considered
I checked existing knotx docs and found it not sufficient.
Additional context
As this documentation should be rendered as a HTML app we can put in a number of checks that will ensure that it is up-to-date.
Basic test could check if linked classes are still present in the gihub repo (and not marked as deprecated)
More complex test could start up the test project and examine knotx logs to verify that listed classes are visible under log.trace and take part in the rendering process (whenever such information is available in the log). In the future we could take advantage of tracing enhancements from Vertx 4.
Is your feature request related to a problem? Please describe. Currently both knotx project and it's documentation are highly fragmented. It could benefit from a single document that would explain how a single request is processed by knotx. I would like to base such documentation on existing sample projects, specifically https://github.com/Knotx/knotx-example-project/tree/master/template-processing/handlebars
Describe the solution you'd like Let's assume we would like to document the flow for template engine. There are four main stages of request processing (repository step, fragment splitter, fragment handler, fragment assembler).
I would like to visualize each one of them as a separate column with blocks representing relevant classes involved in the processing. For each block I'd like to see:
I would like to include all relevant data for at list single test scenario. That means I would like to be able to expand list of Fragments and examine a JSON representation of each one of them - same as during debug of a deployed application.
If a certain stage has more classes involved in the processing (for Fragment Handler it would be Fragment Engine, Task Engine etc) additional blocks can be added further down in the column representing given stage.
This fiddle can serve as a reference: https://jsfiddle.net/orqb7xvn/2/
I would also like to see how OpenApi is configured (openapi.yaml) and how config files from knotx-stack are referenced in project-specific files (in this case operations.conf from knotx-example-project).
Describe alternatives you've considered I checked existing knotx docs and found it not sufficient.
Additional context As this documentation should be rendered as a HTML app we can put in a number of checks that will ensure that it is up-to-date.
Basic test could check if linked classes are still present in the gihub repo (and not marked as deprecated)
More complex test could start up the test project and examine knotx logs to verify that listed classes are visible under log.trace and take part in the rendering process (whenever such information is available in the log). In the future we could take advantage of tracing enhancements from Vertx 4.