Update docs

docs/description.md

@@ -1,9 +1,16 @@
 # How This Works
+Read this page if you want a deeper understanding of how this works (for instance, for the purpose of contributing).
 
-After installing this package and running the command `php artisan scribe:generate` in your application, here's what happens:
-
-- The package fetches all your application's routes.
-- It looks through your [configuration file](config.md) to filter the routes to the ones you actually want to document. For each route, it retrieves the settings you want to apply to it, if any.
-- It processes each route. "Process" here involves using a number of strategies to extract the route's information: group, title, description, body parameters, query parameters, and a sample response, if possible.
-- After processing the routes, it generates a markdown file describing the routes from the parsed data and passes them to [Pastel](https://github.com/knuckleswtf/pastel), which wraps them in a theme and converts them into HTML and CSS.
-- It generates a Postman API collection for your routes. ([This can be disabled.](config.html#postman))
+- When the `generate` command is run, the Generator fetches all your application's routes from Laravel's (or DIngo's) Route facade.
+- Next, the RouteMatcher uses the rules in your config to determine what routes to generate documentation for, as well as extract any specific configuration for them. This configuration is passed to the next stages.
+- The Generator processes each route. This means fetching the route action (controller, method) and using the configured strategies to extract the following:
+  - route metadata (name, description, group name, group description, auth status)
+  - url parameters
+  - body parameters
+  - query parameters
+  - headers
+  - fields in the response
+  - sample responses
+- Next, the Writer uses information from these parsed routes and other configuration to generate a Markdown file via Blade templating.
+- This Markdown file is passed to [Pastel](https://github.com/knuckleswtf/pastel), which wraps them in a theme and converts them into HTML, CSS and JS.
+- If enabled, a Postman collection is generated as wel, via the PostmanCollectionWriter.

docs/guide-getting-started.md

@@ -1,17 +1,114 @@
 # Getting Started
 
-## What routes do I want to document?
+## Setup the package
+First, install the package:
 
+```bash
+composer install knuckleswtf/scribe 
+```
 
+Next, publish the config file.
+
+```bash
+php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config
+```
+
+This will create a `scribe.php` file in your config directory. Cool, now you're ready to take it for a spin.
+
+## First: What routes do I want to document?
+The first thing to do is decide what routes you want to document. By default, Scribe will try to document all of your routes. You should take a moment to configure this in the `scribe.php`. Let's look at the `routes` section. It looks like this (with some comments):
+
+```php
+
+    'routes' => [
+        [
+            'match' => [
+                'domains' => ['*'],
+                'prefixes' => ['*'],
+                'versions' => ['v1'],
+            ],
+            'include' => [
+                // 'users.index', 'healthcheck*'
+            ],
+            'exclude' => [
+                // '/health', 'admin.*'
+            ],
+            'apply' => [
+                'headers' => [
+                    'Content-Type' => 'application/json',
+                    'Accept' => 'application/json',
+                ],
+                'response_calls' => [
+                    'methods' => ['GET'],
+                    'config' => [
+                        'app.env' => 'documentation',
+                        'app.debug' => false,
+                    ],
+                    'cookies' => [
+                        // 'name' => 'value'
+                    ],
+                    'queryParams' => [
+                        // 'key' => 'value',
+                    ],
+                    'bodyParams' => [
+                        // 'key' => 'value',
+                    ],
+                ],
+            ],
+        ],
+    ],
+
+```
+
+With Scribe, you split up your routes into route groups. Each entry in the `routes` array is a single group. The main purpose of these groups is so you can apply different settings to multiple endpoints in one go. For instance, for some routes, you'd like an `Api-Version` header to be added to some routes, but not others, you can easily configure that here. By default, all your routes are in a single group, and we recommend leaving them like that. You can split your routes later if you realise you need to.
+
+Another important setting is the `router` key. If you're using Dingo, you should change this to `dingo`.
+
+The last important setting to take note of is `apply.response_calls`. A "response call" is Scribe hitting your API to try to generate an example response to display in your docs. The package tries to play it safe by using database transactions (so no data is modified). Additionally, response calls are only enabled for `GET` requests by default. You can configure the behaviour of response calls here. For now, we can leave them as on for GETs only.
+
+## Pick a documentation type
+We're almost ready to try it out. Just one more thing. How do you want your documentation to be routed? This is set in the `type` key in the config. You have two options:
+- As a simple set of HTML/CSS/JavaScript files (type = `static`): This generates a single `index.html` file (plus CSS and JS assets) to your public/docs folder. The benefit of this is that it's easy; on your local machine, you can just right-click the file and "Open in Browser", and on your server, just visit <your-public-url>/docs. The routing of this file does not pass through Laravel. The downside of this is that you cannot easily add authentication, or any other middleware.
+- As a Blade view through your Laravel app (type = `laravel`): Use this type if you want to add auth or any middleware to your docs, or if you just prefer serving it through Laravel. With this type, Scribe will automatically add the corresponding Laravel route for you, but you can customize this.
+  
+ 
 ## Do a test run
+Now, let's do a test run. Run the command to generate your docs.
+
+```bash
+php artisan scribe:generate
+```
 
+Open up your docs in your browser. If you're using `static` type, just find the `docs/index.html` file in your public/ folder. If you're using `laravel` type, start your app (`php artisan serve`), then visit `/doc`. You should see your docs show up nicely.
+
+There's also a Postman collection generated for you by default. You can get it by visiting `/docs/collection.json` for `static` type, and `/doc.json` for `laravel` type.
 
 ## Add information about your API
+Now you can add more detail to your documentation. Here are some things you can customise:
+- The introductory text
+- Authentication information
+- Languages for the example requests
+- A logo to show in your docs.
 
+For details, check out []().
 
 ## Add information to your routes
+Scribe tries to figure out information about your routes, but it needs more help from you to go far. Here's some information you can enrich:
+- Groups (you can group your endpoints by domain eg User management, Order information)
+- URL parameters
+- Request Headers
+- Body parameters
+- Query parameters
+- Example responses
+- Fields in the response
+
+Check out how to do this in the guide on [Documenting your API]().
+
+## Generate and publish
+After making changes as needed, you can run `php artisan scribe:generate` as many times as you want. You should also check out the [Helpful Tips]() guide.
 
+When you're happy with how your documentation looks, you're good to go. You can add the generated documentation to your version control and deploy as normal, and your users will be able to access it as you've configured.
 
-## Generate
 
-## Publish
+## Need advanced customization?
+Don't like how the template looks? Want to change how things are arranged, or add a custom language for the examples? Thinking of custom ways to extract more information about your routes?  Check out the guide on [advanced customization]()/.

docs/helpful-tips.md

@@ -0,0 +1,5 @@
+# Helpful Tips
+
+## Use a separate env for generating documentation
+
+## Minimize usage of route groups

docs/index.md

@@ -1,20 +1,22 @@
 # Overview
 
-Automatically generate your API documentation from your existing Laravel/Lumen/[Dingo](https://github.com/dingo/api) routes. [Here's what the output looks like](https://shalvah.me/TheCensorshipAPI/).
+AGenerate API documentation for humans from your Laravel/Lumen/[Dingo](https://github.com/dingo/api) codebase. [Here's what the output looks like](https://shalvah.me/TheCensorshipAPI/).
 
-`php artisan scribe:generate`
+> Coming from mpociot/laravel-apidoc-generator? Check out [what's new](whats-new.md) and the [migration Guide](migrating.md). Otherwise, check out the [Getting Started guide](guide-getting-started.md).
 
 ## Contents
-* [How This Works](description.md)
+* [Getting started](guide-getting-started.md)
+* [Migrating from mpociot/laravel-apidoc-generator](migrating.md)
 * [Configuration](config.md)
-* [Migrating from v3 to v4](migrating.md)
 * [Generating Documentation](generating-documentation.md)
 * [Documenting Your API](documenting.md)
+* [Helpful Tips](helpful-tips.md)
+* [Advanced Customization](customization.md)
+* [How This Works](description.md)
 * [Extending functionality with plugins](plugins.md)
-* [Internal Architecture](architecture.md)
 
 ## Installation
-> Note: PHP 7 and Laravel 5.5 or higher are required.
+> Note: PHP 7.2 and Laravel 5.8 or higher are required.
 
 ```sh
 composer require knuckleswtf/scribe
@@ -26,7 +28,7 @@ Publish the config file by running:
 ```bash
 php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config
 ```
-This will create an `scribe.php` file in your `config` folder.
+This will create a `scribe.php` file in your `config` folder.
 
 ### Lumen
 - Register the service provider in your `bootstrap/app.php`:

docs/migrating.md

@@ -1,41 +1,55 @@
 # Migrating from mpociot/laravel-apidoc-generator to Scribe v1
-There's quite a few changes in Scribe, and this guide aims to show you everything notable, as well as provide direct steps to migrate. Note that if you've customized your installation of mpociot/laravel-apidoc-generator heavily, you might want to copy your changes out and just start afresh, then manually merge your changes in. This guide should show you the key parts you need to change.
+There's quite a few changes in Scribe, and this guide aims to show you the key parts you need to look out for so things don't break. After migrating, you should also check out the [list of new features](./whats-new.html).
 
 ## Requirements
 - PHP version: 7.2+
 - Laravel/Lumen version: 6+
 
 ## Before you start
-- If you've modified your generated Markdown or Blad views, I recmmend you copy them out first.
-- Rename your old config file (for instance, from `apidoc.php` to `scribe.old.php`). Then install Scribe and publish the new config file via `php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config`. Then copy over any changes you've made in the old one and delete it when you're done.
+- Remove the old package and install the new one:
 
-## Configuration
-Here are changes to look out for in `scribe.php`:
+```bash
+composer remove mpociot/laravel-apidoc-generator 
+composer install knuckleswtf/scribe 
+```
 
+- Publish the new config file: 
+
+```bash
+php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config
+```
+
+At this point, you should have _both_ apidoc.php and scribe.php in your config folder. This is good, so ou can easily copy your old config over and delete when you're done.
+
+If you've modified your generated Blade views, you should also publish the new ones:
+
+```bash
+php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-views
+```
+
+> ⚠ IMPORTANT: If you've modified the generated Markdown or added prepend/append files, you should copy them to a separate folder (not in `resources/docs`). After generating the new docs, you'll have to manually add your changes in.
+
+_After you've done all of the above_, delete your `resources/docs/` and `public/docs` folders, to prevent any conflicts with the new ones we'll generate. If you're using `laravel` type output, you can also delete `resources/views/apidoc/`.
+
+## Key changes
 ### High impact
 - The `laravel.autoload` key is now `laravel.add_routes`, and is `true` by default.
+- The Markdown output is now a set of files, located in `resources/docs`. The route files are located in `resources/docs/groups` and are split by groups (1 group per file).
+- The `rebuild` command has been removed. By default, when you run `php artisan scribe:generate`, Scribe will not overwrite any Markdown files you've modified. If you want Scribe to do so, run with `--force`. 
 
 ### Low impact
 - `logo` is now `false` by default, so no logo spot will be shown. Relative paths and URLs are now supported too.
-- We've added some new keys to the config file (`auth`, `info_text`). You might want to leverage them, so take a good look at what's available. 
 
-## Class names
+## Advanced users
 It's a new package with a different name, so a few things have changed. This section is especially important if you've written any custom strategies or extended any of the provided classes.
 
-### High impact
-
-
-## Assets
-- If you've published the vendor views, rename them (for instance to `route.old.blade.php`). Publish the new views via `php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-views`. Compare the two views and reconcile your changes, then delete the old views. 
-
-The major change here is the introduction of the `responseFields` section and the addition of `description` for `responses`.
-
-- The location of the source files for the generated docs has changed. Move any prepend/append files you've created from `public/docs/source` to the new location (`resources/docs/source`)
+- Replace all occurrences of `Mpociot\ApiDoc\Strategies` with `Knuckles\Scribe\Extracting`
+- Replace all occurrences of `Mpociot\ApiDoc\Strategies\RequestHeaders` with `Knuckles\Scribe\Extracting\Strategies\Headers`
+- Replace all occurrences of `Mpociot\ApiDoc` with `Knuckles\Scribe`
+- For strategies, change the type of the `$method` argument to the `__invoke` method from `ReflectionMethod` to `ReflectionFunctionAbstract`. It's a superclass, so every other thing should work fine.
+- For each strategy, add a `public $stage` property and set it to the name of the stage the strategy belongs to. If you have a constructor defined, remove the `$stage` argument from it. 
+- The `requestHeaders` stage has been renamed to `headers`.
+- If you've published the views, you'll note that they are now in a different format. See the documentation on [customising the views]() to learn the new look.
 
-## API
-- Verify that any custom strategies you've written match the new signatures. See [the docs](plugins.html#strategies). Also note the order of execution and the new stages present.
 
-## Other new features (highlights)
-- [Non-static docs/docs with authentication](config.html#type)
-- [`@apiResource` for Eloquent API resources](documenting.html#apiresource-apiresourcecollection-and-apiresourcemodel)
-- You can now mix and match response strategies and status codes as you like.
+That should be all. Head on to the [list of new features](./whats-new.html) to see what's new. If you come across anything we've missed, please send in a PR!

docs/whats-new.md

@@ -18,7 +18,7 @@ Scribe can now add authentication information to your docs! The info you provide
 You can now customise the introductory text shown at the start of your documentation🙌. Full Markdown and HTML support, plus some nice little CSS classes to make things 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.
 
 ## FormRequest support is back!🎉🎉🎉
-Yes, you've wanted it for a long time, and it's back.😄 We thought long and hard about how we could leverage what the framework gives to make devs' lives easier, and we realized that even though FormRequests are for validation, not documentation, they still contain useful business logic we can extract, so we decided to bring this back (with some conditions, though👀), and we're exploring ways to support other validation approaches. [Head over to the docs]() to know what you need to do to use this.
+Yes, you've wanted it for a long time, and it's back.😄 We thought long and hard about how we could leverage what the framework gives to make devs' lives easier, and we realized that even though FormRequests are for validation, not documentation, they still contain useful business logic we can extract. So we decided to bring this back (with some conditions, though👀), and we're exploring ways to support other validation approaches. [Head over to the docs]() to know what you need to do to use this.
 
 ## 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]().
@@ -33,7 +33,7 @@ For both Eloquent API resources and league/fractal transformers, you can now spe
 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. 
 
 ## 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 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 `requestHeaders` stage has been renamed to `headers`.
 
 [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]().
 
@@ -42,6 +42,8 @@ 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]()
+- The output Markdown is now split across multiple files.
+- The default group is now called "Endpoints".
 - 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.
 
-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!👋
+Well, if you're ready to get going, head over to the [migration guide](). We've done our best to describe what you need to look out for. Have a great day!👋

todo.md

@@ -1,8 +1,15 @@
 # Documentation tasks
-- Migration guide
 - Contribution guide
 - Set up plugin wiki
-- Rewritten docs
+- Rewritten docs. Some things to document:
+  - formrequests: supported rules
+  - hideFromAPIDocumentation
+  - overwriting with --force
+  - binary responses
+  - troubleshooting: --verbose
+  - plugin api: responses - description, $stage property
+  - --env
+  - Use database transactions and `create()` when instantiating factory models
 
 # Release blocker
 - Port recent changes from old repo