[REQ] Provide step-by-step documentation for creating custom templates and/or generators

I found that the generator for our server platform (Restbed) is not generating usable code. So I started wading through the customization documentation, but it's just too opaque for me to make much headway. It does not describe how we go from an API description in OAS YAML to generating files with a desired syntax.

I assume the generator must parse the OAS document into a common data model, and then pipe that model through the Mustache templates to generate the files. But I can't find any reference to what that data model is or how Mustache works. And on top of that, we have Java configuration files for every generator, which set options that likewise I can't find a catalog of.

And even on top of that, the docs offhandedly mention things like, "You might have an external configuration file named config.yaml which defines additional properties like this for a kotlin client generator..."

But it doesn't say how we know the structure of such a config file or all the things we might populate it with. There are so many files filled with undocumented data-element placeholders and references interacting... I'm mystified as to how to wade through them. Looking at the existing ones helps a little, of course, but is far from a complete-enough picture.

As it stands, I guess I have to abandon code generation and hand-code our entire server API, or write a new generator from scratch. But that seems like a pity when a lot of work has been done here. And I intend no insult to the documentation contributors; this is just how it looks to a newcomer. Am I missing some documentation somewhere?

Update: Now I've found a couple more caches of doc, slightly more orderly but relationship unclear. We have the one at the .tech domain, which seems most promising. But before that I looked at the Wiki page, some of which said it was out of date and referred to the .tech one.

And through all that, I've encountered two different means of generating starter code: the "meta" option on the generator, and then new.sh in the root of the generator source tree. So that's at least three sets of doc and two boilerplate generators so far.

Start by comparing docs/customization.md, the .tech docs/new-generator page, the Wiki's Building-your-own-Templates page, and new.sh to map the intended workflow. Document how an OAS YAML description reaches the data model and Mustache templates, how Java generator options and config.yaml are structured, and when to use each starter-generation method.