Generate examples

[romalytvynenko]

Real examples in docs are awesome, so why not?

Quote from Discord:

Good question! I gave it some thoughts and this is definitely an interesting problem to solve.

To discover model factories I will probably use default Laravel mechanism: simply calling SomeModel::factory(). So for the simplest case you even won't need to modify/add something: Scramble will try to do SomeModel::factory()->make() and if successful, it will generate docs example from it.

The interesting part is that examples will need to be generated by triggering some command. Something like php artisan scramble:generate-examples. And whatever this command generates, will need to be pushed into git. This is due to the real life examples are just too complex to be generated by simply calling make on factory. I imagine that for some examples you'll need to make related models that need to be persisted into DB. So this is why I see it as a separate command. Results of this command will then be used by during docs generation, giving you beautiful examples with actual values.

To make sure your examples are up-to-date, the command will have --dry-run flag which you can run on CI. It will let you know if generated examples are changed (or generating examples code, if used, is broken). So you will be able to update examples and push results to Github.

Summarizing, examples are really more advanced use-case, but I still hope that having it organized like so (you call a command - you have examples) will have decent DX.