[feature]: Documentation UI

[andrewm-aero]

Feature Description

As a Software Factory Operator, I want my tenants and users to have easy-to-read and easy-to-find documentation on available templates, libraries, and configurations embedded into the Jenkins UI, extracted from the JTE groovy files.

As the size of our JTE configuration has grown, managing the documentation of available features and options to our users has become an increasing chore. I believe that the ideal case would be to have a page similar in structure and motivation to the Job DSL plugin's API Viewer which scans all configured library and configuration repositories, extracts Javadoc-style comments for each template, library, and library config field, and keyword, and presents them in a searchable HTML page.

[steven-terrana]

that's a really interesting idea.

The jte-library-scaffold that provides a way to build a library source repository that's integrated with the same documentation framework JTE uses for its documentation.

Maybe it's an endpoint that maps to a site like this?

[steven-terrana]

the javadoc approach is interesting too.

Perhaps groovy already has some functionality to make this possible.

the aggregation across sources might be tricky though since templates, configs, and libraries can come from many sources at the same time

[andrewm-aero]

I'm not terribly picky about which documentation framework is used, so long as there is one recognized by the plugin, and so long as it can take multiple sources and "stitch" them together into a cohesive, searchable page (or set of pages) within the Jenkins UI. If this framework can do that, and it comes with the JTE maintainer's recommendation, I'm happy to learn it. If that's case, would it be reasonable to have the JTE check out the libraries/configs on startup, run the docs generator, and add it as static page to Jenkins? There'd probably need be some way to have it regenerate when new commits are made to the JTE repos, though.

For the Javadoc approach, the reason I like it is that one can embed the docs directly in the groovy, and not have to manage updating names in multiple places, and it might even be able to determine type validation information, required vs optional, etc, and auto-generate that info in the HTML.