Update doc

docs/documenting.md

@@ -355,3 +355,39 @@ If you don't specify an example response using any of the above means, this pack
 - By default, the package will generate dummy values for your documented body and query parameters and send in the request. If you specified example values using `@bodyParam` or `@queryParam`, those will be used instead. You can configure additional parameters or overwrite the existing ones for the request in the `queryParams`, and `bodyParams` sections.
 
 - The `ResponseCalls` strategy will only attempt to fetch a response if there are no responses with a status code of 2xx already.
+
+
+
+## Documenting responses
+ This functionality is provided by default by the `UseResponseFieldTags` strategy. You use it by adding a `@responseField` annotation to your controller method.
+
+```
+@responseField id integer The id of the newly created user
+```
+
+Note that this also works the same way for array responses. So if your response is an array of objects, you should only mention the keys of the objects inside the array. So the above annotation will work fine for both this response:
+
+```
+{
+  "id": 3
+}
+```
+
+and this:
+
+```
+[
+  { "id": 3 }
+]
+```
+
+You can also omit the type of the field. Scribe will try to figure it out from the 2xx responses for that endpoint. So this gives the same result:
+
+```
+@responseField id integer The id of the newly created user
+```
+
+Result:
+
+![](./images/response-fields.png)
+

docs/plugins.md

@@ -174,3 +174,10 @@ Each strategy class must implement the __invoke method with the parameters as de
 Responses are _additive_. This means all the responses returned from each stage are added to the `responses` array. But note that the `ResponseCalls` strategy will only attempt to fetch a response if there are no responses with a status code of 2xx already.
 
 - In the `headers` stage, you can return an array of headers. You may also negate existing headers by providing `false` as the header value.
+
+
+
+
+
+## Reworked Strategy API
+- `stage` property.

docs/whats-new.md

@@ -1,47 +1,47 @@
-## Documenting responses
-You can now give readers more information about the fields they can expect in your responses. This functionality is provided by default by the `UseResponseFieldTags` strategy. You use it by adding a `@responseField` annotation to your controller method.
+# What's new in Scribe
+> This page is written for those coming from mpociot/laravel-apidoc-generator. It should give you an overview of what's new in Scribe, and point you to the relevant documentation on each. Once you're ready to migrate, check out [the migration guide]().
 
-```
-@responseField id integer The id of the newly created user
-```
+Scribe v1 comes with some new features and tweaks aimed at improving the developer experience and the quality of the output documentation. Let's dive in!
 
-Note that this also works the same way for array responses. So if your response is an array of objects, you should only mention the keys of the objects inside the array. So the above annotation will work fine for both this response:
+## Improved appearance
+First off, the generated documentation has been given a UI refresh. We've made some cosmetic fixes like changing the custom font, removing the logo by default, switching from tables to explanatory paragraphs. [Here's a walkthrough on what to expect](). Of course, there's still lots of room for improvement. If you can do some sick CSS, consider making a PR to knuckleswtf/pastel, as that's where the templates live.
 
-```
-{
-  "id": 3
-}
-```
+## Authentication information 🔐
+Scribe can now add authentication information to your docs! The info you provide will be used in generating a description of the authentication text, as well as adding the needed parameters in the example requests, and in response calls. See more [here]().
 
-and this:
+## Describing responses
+ You can now give readers more information about the fields they can expect in your responses, by adding a description for what each field is. [Details here]().
+ 
+ Also, you can describe multiple responses with the same (or different) status code, but applying to different scenarios. Check it out [here]().
 
-```
-[
-  { "id": 3 }
-]
-```
-
-You can also omit the type of the field. Scribe will try to figure it out from the 2xx responses for that endpoint. So this gives the same result:
+## More customization options
+You can now customise the introductory text shown at the start of your documentation.🙌 This is done by setting the `intro_text` key in the config. Full Markdown and HTML support, plus some nice little CSS classes to make thigns pretty. If you want to go even deeper and modify the output templates, we have some nice Blade components you can use. See [the docs]() for details.
 
-```
-@responseField id integer The id of the newly created user
-```
+## FormRequest support is back!🎉🎉🎉
+Yes, you've wanted it for a long time, and it's back.😄 We thought long and hard about howwe could leverage what the framework gives to make devs' lives easier, so we decided to bring this back. [Head over to the docs]() to know what you need to do to use this.
 
-Result:
+## Automatic routing for `laravel` docs
+The `autoload` key in `laravel` config is now `add_routes`, and is `true` by default. This means you don't have to do any extra steps to serve your docs through your Laravel app (if you're using `laravel` type). [Details here]().
 
-![](./images/response-fields.png)
+## Simplified commands
+There's no more `rebuild` command. We removed that, because it was confusing, even to us. Now there's a single `scribe:generate` command that will skip any Markdown files you've modified, except you use --force. [Details]().
 
+## Enhanced API Resource and Transformers support
+For both Eloquent API resources and league/fractal transformers, you can now specify relations to be loaded with your models, states to use when loading from factories, and pagination options. Factory operations now run in database transactions and use create(), so your related models should be created properly now. [See the docs]().
 
-## Automatic routing for `laravel` docs
-The `autoload` key in `laravel` config is now `add_routes`, and is `true` by default. This means you don't have to do any extra steps to serve your docs through you Laravel app.
+## --env support
+Okay, this isn't actually new, but we thought we'd draw your attention to it. You can specify the .env file to be loaded when documenting (say, .env.docs) by passing in `--env`, as in `php artisan scribe:generate --env docs`. This can be very useful for response calls and fetching example models from test databases. 
 
-## Authentication
-Scribe can now add authentication information to your docs! To get this, you'll need to use the `auth` section in the config file.
+## Reworked Strategy API
+The API for creating strategies has been improved. Each strategy now has a `stage` property that describes the stage it belongs to (previously, this value was passed via the constructor, which didn't make sense). There's a new stage, `responseFields`, and the `responses` stage now supports another field, `description`.
 
-The info you provide will be used in generating a description of the authentication text, as well as adding the needed parameters in the example requests, and in response calls. See that section of the docs for details.
+[Coming soon] Plus, there's also a new `scribe:strategy` command that can help you easily generate strategies. And we now have a wiki containing a list of useful strategies contributed by community members. See [the docs on plugins]().
 
-## More customization options
-You can now customise the introductory text by setting the `intro_text` key in your scribe.php. 
+## Other changes
+A few other things that might interest some folk:
+- [Closure routes can now be documented]()
+- [Binary responses can now be indicated]()
+- [Coming soo] [File upload inputs are supported, too]()
+- If you're interested in contributing, we've also added a [guide for that](). We've reworked the tests structure as well to make it easier to maintain.
 
-## Reworked Strategy API
-- `stage` property.
+Well, if you're ready to get going, head over to the [migration guide](). It's not a small task, but we've done our best to describe what you need to look out for. Have a great day!👋

todo.md

@@ -1,3 +1,9 @@
-- improve error messaging: there's lots of places where it can crash because of wrong user input. We can try to have more descriptive error messages.
-- scribe:strategy: It would be nice if we had a make strategy command that can help people generate custom strategies
-- File upload input: see # . The primitive typer `file` has already been added to FormRequest support, but with no example value
+- Migration guide
+- Contribution guide
+- Rewritten docs
+- File upload input: see # . The primitive type `file` has already been added to FormRequest support, but with no example value
+- Find out a way to make automatic routing for Laravel work with /docs instead of /doc
+- Add tests that verify the overwriting behaviour of the command when --force is used
+- Command scribe:strategy: It would be nice if we had a make strategy command that can help people generate custom strategies
+- Improve error messaging: there's lots of places where it can crash because of wrong user input. We can try to have more descriptive error messages.
+