Clean up docs

docs/customization.md

@@ -108,3 +108,6 @@ There are also a number of included components that you can utilize in your Blad
 ![](images/customization-methods-badge-2.png) 
 
 - `badges/base.blade.php`: The base badge component, used by `auth` and `http-method`. Takes in `colour` and `text` attributes, and uses Pastel's badge classes to create a badge.
+
+## Changing the CSS styles
+The CSS styling is provided by Pastel, which currently supports only one template. Consider making a pull request to add your alternative styles.

docs/documenting-endpoint-metadata.md

@@ -1,7 +1,7 @@
 # Specifying metadata about an endpoint
 
 ## Endpoint title and description
-To set an endpoint's title and description, just write in the method's docblock. The first paragraph will be used as the title, the rest as the description. Custom formatting (such as `<aside>` tags) is also supported (see the [Pastel docs](http://github.com/knuckleswtf/pastel))
+To set an endpoint's title and description, just write in the method's docblock. The first paragraph will be used as the title, the rest as the description. Custom formatting (such as `<aside>` tags) is also supported (see the [Pastel docs](http://github.com/knuckleswtf/pastel)).
 
 For instance, this:
 
@@ -27,7 +27,10 @@ All endpoints are grouped for easy navigation.
 
 To add all endpoints in a controller to a group, use `@group` in the controller docblock, followed by the group's title. You can also add a description below the group.
 
+```eval_rst
+.. Tip:: 
 You can also specify an `@group` on a single method to override the group defined at the controller level.
+```
 
 ```php
 /**
@@ -65,7 +68,9 @@ Grouping endpoints is optional. Any endpoints not in a group will be placed in a
 ## Indicating authentication status
 You can use the `@authenticated` annotation on a method to indicate if the endpoint is authenticated. A "Requires authentication" badge will be added to that route in the generated documentation. 
 
-If all the routes in a controller are authenticated, you can specify `@authenticated` in the controller doc block instead. 
+```eval_rst
+.. Tip:: If all the routes in a controller are authenticated, you can specify `@authenticated` in the controller doc block instead. 
+```
 
 ```php
     /**

docs/guide-getting-started.md

@@ -45,7 +45,7 @@ First, let's add some general info about the API. Here are some things you can c
 - Languages for the example requests
 - A logo to show in your docs.
 
-For details, check out []().
+For details, check out [Documenting API information](documenting-api-information.html).
 
 ## Choose your routes
 Next up, decide what routes you want to document. This is configured in the `routes` key of `scribe.php`. By default, Scribe will try to document all of your routes, so if you're okay with that, you can leave it at that.
@@ -96,14 +96,12 @@ If you'd like to exclude some routes, there are two ways:
     ],
 ```
 
-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. You can also configure [response calls](documenting-endpoint-responses.html#response-calls) in here.
+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. You can also configure [response calls](documenting-endpoint-responses.html#generating-responses-automatically-via-response-calls) in 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. 
 
 [Here's the full documentation on configuring routes](config.html#routes).
 
-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.
-
 ## 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")
@@ -122,4 +120,4 @@ After making changes as needed, you can run `php artisan scribe:generate` as man
 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.
 
 ## 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](customization.html).
+Don't like how the template looks? Want to change how things are organized, 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](customization.html).

docs/index.md

@@ -2,7 +2,11 @@
 
 Generate 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/).
 
-> 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).
+
+```eval_rst
+.. admonition:: Wondering where to get started?
+If you're 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
 * [Getting started](guide-getting-started.md)
@@ -14,7 +18,7 @@ Generate API documentation for humans from your Laravel/Lumen/[Dingo](https://gi
 * [Specifying headers to be sent in requests to the endpoint](documenting-endpoint-headers.md)
 * [Documenting query parameters and URL parameters to be sent in requests to the endpoint](documenting-endpoint-query-parameters.md)
 * [Documenting body parameters and files to be sent in requests to the endpoint](documenting-endpoint-body-parameters.md)
-* [Documenting example responses returned from the endpoint](documenting-endpoint-responses.md)
+* [Documenting possible responses returned from the endpoint](documenting-endpoint-responses.md)
 * [Generating Documentation](generating-documentation.md)
 * [Configuration](config.md)
 * [Helpful Tips](helpful-tips.md)

docs/migrating.md

@@ -2,8 +2,8 @@
 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+
+- PHP version: 7.2.5+
+- Laravel/Lumen version: 5.8+
 
 ## Before you start
 - Remove the old package and install the new one:
@@ -52,13 +52,12 @@ You can also use a URL.
 ## 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.
 
-- Replace all occurrences of `Mpociot\ApiDoc\Strategies` with `Knuckles\Scribe\Extracting\Strategies`
-- Replace all occurrences of `Mpociot\ApiDoc\Strategies\RequestHeaders` with `Knuckles\Scribe\Extracting\Strategies\Headers`
+- Replace all occurrences of `Mpociot\ApiDoc\Extracting\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.
+- If you've published the views, you'll note that they are now in a different format. See the documentation on [customising the views](customization.html#changing-the-markdown-templates) to learn the new look.
 
 
 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

@@ -1,5 +1,7 @@
 # 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](migrating.html).
+```eval_rst
+.. Note:: This page is written for devs 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 <migrating.html>`_.
+```
 
 Scribe v1 comews with some new features and tweaks aimed at improving the developer experience and the quality of the output documentation. Let's dive in!
 

src/Writing/PostmanCollectionWriter.php

@@ -106,7 +106,8 @@ class PostmanCollectionWriter
                 'Accept' => 'application/json',
             ])
             ->map(function ($value, $header) {
-                // Fix so in config we can have @{{ for blade views but it'll use {{ for postman for env vars. 
+                // Allow users to write ['header' => '@{{value}}'] in config
+                // and have it rendered properly as {{value}} in the Postman collection.
                 $value = str_replace('@{{', '{{', $value);
                 return [
                     'key' => $header,