Update config docs

config/scribe.php

@@ -41,7 +41,7 @@ return [
 
         /*
          * Where is the auth value meant to be sent in a request?
-         * Options: query, body. query_or_body, basic, bearer, header (for custom header)
+         * Options: query, body, query_or_body, basic, bearer, header (for custom header)
          */
         'in' => 'bearer',
 
@@ -51,13 +51,14 @@ return [
         'name' => 'token',
 
         /*
-         * The value of the parameter. This will NOT be part of the generated documentation.
-         * Use it to easily auth response calls by this package. Otherwise, we'll use a random value.
+         * The value of the parameter to be used by Scribe to authenticate response calls.
+         * This will NOT be included in the generated documentation.
+         * If this value is null, Scribe will use a random value.
          */
         'use_value' => env('SCRIBE_AUTH_KEY'),
 
         /*
-         * Any extra info for your users. For instance, you can describe where to find (or generate) their auth credentials.
+         * Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials.
          * Markdown and HTML are supported.
          */
         'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
@@ -128,7 +129,7 @@ INTRO
     'default_group' => 'Endpoints',
 
     /*
-     * Custom logo path. The will be used as the value of the src attribute for the <img> tag,
+     * Custom logo path. This will be used as the value of the src attribute for the <img> tag,
      * so make sure it points to a public URL or path accessible from your web server. For best results the image width should be 230px.
      * Set this to false to not use a logo.
      *

docs/config.md

@@ -1,89 +1,152 @@
 # Configuration
-[IN PROGRESS]
+Here's a rundown of what's available in the `config/scribe.php` file. 
 
-Before you can generate your documentation, you'll need to configure a few things in your `config/scribe.php`. If you aren't sure what an option does, it's best to leave it set to the default. If you don't have this config file, see the [installation instructions](index.html#installation).
+```eval_rst
+.. Tip:: If you aren't sure what an option does, it's best to leave it set to the default.
+```
 
-## `type`
+## Output settings
+### `type`
 This is the type of documentation output to generate.
 - `static` will generate a static HTMl page in the `public/docs` folder, so anyone can visit your documentation page by going to {yourapp.domain}/docs.
 - `laravel` will generate the documentation as a Blade view within the `resources/views/scribe` folder, so you can add routing and authentication.
 
-> In both instances, the source markdown file will be generated in `resources/docs`.
+```eval_rst
+.. Note:: In both instances, the source markdown file will be generated in `resources/docs`.
+```
 
-## `laravel`
-If you're using `laravel` type output, this package can automatically set up an endpoint for you to view your generated docs. You can configure this here.
+### `laravel`
+Settings for the `laravel` type output.
 
-### `add_routes`
-Set this to `true` if you want the documentation endpoint to be automatically set up for you. Of course, you can use your own routing instead, by setting this to `false`.
+- `add_routes`: Set this to `true` if you want the documentation endpoint to be automatically set up for you. Of course, you can use your own routing instead, by setting this to `false`.
 
-### `docs_url`
-The path for the documentation endpoint (if `add_routes` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/docs.json`). Default: `/docs`
+- `docs_url`: The path for the documentation endpoint (if `add_routes` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/docs.json`). Default: `/docs`.
 
-### `middleware`
-Here, you can specify middleware to be attached to the documentation endpoint (if `add_routes` is true).
+- `middleware`: List of middleware to be attached to the documentation endpoint (if `add_routes` is true).
 
-## `router`
-The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)
+### `base_url`
+The base URL to be used in examples and the Postman collection. By default, this will be the value of `config('app.url')`.
 
-## `base_url`
-The base URL to be used in examples and the Postman collection. By default, this will be the value of config('app.url').
+### `intro_text`
+The text to place in the "Introduction" section. Markdown and HTML are supported.
 
-## `postman`
-This package can automatically generate a Postman collection for your routes, along with the documentation. This section is where you can configure (or disable) that.
-- For `static` docs (see [type](#type)), the collection will be created in `public/docs/collection.json`, so it can be accessed by visiting {yourapp.domain}/docs/colllection.json.
-- For `laravel` docs, the collection will be generated to `storage/app/scribe/collection.json`. Setting `laravel.add_routes` to true will add a `/docs.json` endpoint to fetch it..
+### `title`
+The HTML `<title>` for the generated documentation, and the name of the generated Postman collection. If this is `null`, Scribe will infer it from `config('app.name')`.
 
-### `enabled`
-Whether or not to generate a Postman API collection. Default: **true**
+### `logo`
+Path to an image file to use as your logo in the generated docs. This will be used as the value of the src attribute for the `<img>` tag, so make sure it points to a public URL or path accessible from your web server. For best results the image width should be 230px. Set this to `false` to not use a logo.
 
-### `name`
-The name for the exported Postman collection. If you leave this as null, this package will default to `config('app.name')." API"`.
+```eval_rst
+.. Important:: If you're using a relative path, remember to make it relative to your docs output location (:code:`static` type) or app URL (:code:`laravel` type). For example, if your logo is in public/img:
+   - for :code:`static` type (output folder is public/docs), use '../img/logo.png'
+   - for :code:`laravel` type, use 'img/logo.png'
+```
 
-### `description`
-The description for the generated Postman collection.
+### `default_group`
+When [documenting your api](documenting.md), you use `@group` annotations to group API endpoints. Endpoints which do not have a group annotation will be grouped under the `default_group`. Defaults to `"Endpoints"`.
 
-## `logo`
-You can specify a custom logo to be used on the generated documentation. Set the `logo` option to an absolute path pointing to your logo file. For example:
-```
-'logo' => resource_path('views') . '/api/logo.png'
-```
+### `example_languages`
+For each endpoint, an example request is shown in each of the languages specified in this array. Currently only `bash`, `javascript`, `php` and `python` are supported. You can add your own language, but you must also define the corresponding Blade view (see [Adding more example languages](customisation#adding-more-example-languages)). Default: `["bash", "javascript"]` 
+ 
+### `postman`
+Along with the HTML docs, Scribe can automatically generate a Postman collection for your routes. This section is where you can configure or disable that.
 
-If you want to use this, please note that the image size must be 230 x 52.
+For `static` output, the collection will be created in `public/docs/collection.json`. For `laravel` output, the collection will be generated to `storage/app/scribe/collection.json`. Setting `laravel.add_routes` to `true` will add a `/docs.json` endpoint to fetch it.
 
-## `default_group`
-When [documenting your api](documenting.md), you use `@group` annotations to group API endpoints. Endpoints which do not have a group annotation will be grouped under the `default_group`. Defaults to **"general"**.
+- `enabled`: Whether or not to generate a Postman API collection. Default: `true`
 
-## `example_languages`
-For each endpoint, an example request is shown in each of the languages specified in this array. Currently only `bash`, `javascript`, `php` and `python` are supported. You can add your own language, but you must also define the corresponding view (see [Specifying languages for examples](generating-documentation.html#specifying-language-for-examples)). Default: `["bash", "javascript"]` 
- 
-##  `faker_seed`
-When generating example requests, this package uses fzanninoto/faker to generate random values. If you would like the package to generate the same example values for parameters on each run, set this to any number (eg. 1234). (Note: alternatively, you can set example values for parameters when [documenting them.](documenting.html#specifying-request-parameters))
+- `description`: The description for the generated Postman collection.
+
+- `auth`: The "Auth" section that should appear in the postman collection. See the [Postman schema docs](https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html) for more information.
+
+## Extraction settings
+### `router`
+The router to use when processing your routes. Can be `laravel` or `dingo`. Defaults to `laravel`.
 
-## `routeMatcher`
-The route matcher class provides the algorithm that determines what routes should be documented. The default matcher used is the included `\Knuckles\Scribe\Matching\RouteMatcher::class`, and you can provide your own custom implementation if you wish to programmatically change the algorithm. The provided matcher must be an instance of the `RouteMatcherInterface`.
-       
-## `fractal`
-This section only applies if you're using [Transformers]() for your API, and documenting responses with `@transformer` and `@transformerCollection`. Here, you configure how responses are transformed.
+### `auth`
+Authentication information about your API. This information will be used:
+- to derive the text in the "Authentication" section in the generated docs
+- to add the auth headers/query parameters/body parameters to the docs and example requests
+- to set the auth headers/query parameters/body parameters for response calls
 
-> Note: using transformers requires league/fractal package. Run `composer require league/fractal to install
+Here are the available settings:
+- `enabled`: Set this to `true` if your API requires authentication. Default: `false`.
 
-### serializer
-If you are using a custom serializer with league/fractal,  you can specify it here. league/fractal comes with the following serializers:
-- \League\Fractal\Serializer\ArraySerializer::class
-- \League\Fractal\Serializer\DataArraySerializer::class
-- \League\Fractal\Serializer\JsonApiSerializer::class
+- `in`: Where is the auth value meant to be sent in a request? Options:
+  - `query` (for a query parameter)
+  - `body` (for a body parameter)
+  - `basic` (for HTTP Basic auth via an Authorization header)
+  - `bearer`(for HTTP Bearer auth via an Authorization header)
+  - `header` (for auth via a custom header)
 
-Leave this as null to use no serializer or return a simple JSON.
+- `name`: The name of the parameter (eg `token`, `key`, `apiKey`) or header (eg `Authorization`, `Api-Key`). When `in` is set to `bearer` or `basic`, this value will be ignored, and the header used will be `Authorization`.
 
-## `routes`
-The `routes` section is an array of items, describing what routes in your application that should be included in the generated documentation. Each item in the array contains rules about what routes belong in that group, and what rules to apply to them. This allows you to apply different settings to different routes.
+- `use_value`: The value of the parameter to be used by Scribe to authenticate response calls. This will **not** be included in the generated documentation. If this value is null, Scribe will use a random value.
 
-Each item in the `routes` array (a route group) has keys which are explained below. We'll use this sample route definition for a Laravel app to demonstrate them:
+- `extra_info`: Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials. Markdown and HTML are supported. This will be included in the `Authentication` section.
+
+### `strategies`
+A nested array of strategies Scribe will use to extract information about your routes at each stage. If you write or install a custom strategy, add it here under the appropriate stage. By default, this is set to:
 
 ```php
-<?php
+    'strategies' => [
+        'metadata' => [
+            \Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
+        ],
+        'urlParameters' => [
+            \Knuckles\Scribe\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class,
+        ],
+        'queryParameters' => [
+            \Knuckles\Scribe\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
+        ],
+        'headers' => [
+            \Knuckles\Scribe\Extracting\Strategies\Headers\GetFromRouteRules::class,
+        ],
+        'bodyParameters' => [
+            \Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromFormRequest::class,
+            \Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
+        ],
+        'responses' => [
+            \Knuckles\Scribe\Extracting\Strategies\Responses\UseTransformerTags::class,
+            \Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseTag::class,
+            \Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseFileTag::class,
+            \Knuckles\Scribe\Extracting\Strategies\Responses\UseApiResourceTags::class,
+            \Knuckles\Scribe\Extracting\Strategies\Responses\ResponseCalls::class,
+        ],
+        'responseFields' => [
+            \Knuckles\Scribe\Extracting\Strategies\ResponseFields\GetFromResponseFieldTag::class,
+        ],
+    ],
+```
 
-Route::group(['domain' => 'api.acme.co'], function () {
+### `routes`
+The `routes` section is an array of items describing what routes in your application that should be included in the generated documentation.
+
+Each item in the `routes` array is a _route group_, an array containing rules defining what routes belong in that group, and what settings to apply to them.
+
+- `match`: Here you define the rules that will be used to determine what routes in your application fall into this group. There are three kinds of rules defined here (keys in the `match` array):
+
+- `domains`: This key takes an array of domain names as its value. Only routes which are defined on the domains specified here will be matched as part of this group. Defaults to `[*]` (routes on all domains).
+ 
+- `prefixes`: The prefixes key is similar to the `domains` key, but is based on URL path prefixes (ie. what the part starts with, after the domain name). Defaults to `[*]` (all routes, regardless of path).
+ 
+```eval_rst
+.. Important:: The `domains` and `prefixes` keys are required for all route groups.
+```
+
+- `versions`: This only applies when `router` is `dingo`. When using Dingo router, all routes must be specified inside versions. This means that you must specify the versions to be matched along with the domains and prefixes when describing a route group.
+
+```eval_rst
+.. Important:: Wildcards in :code:`versions` are not supported; you must list out all the versions you want to match.
+ ```
+ - `include`: A list of patterns (route names or paths) which should be included in this group, *even if they do not match the rules in the `match` section*.
+
+- `exclude`: A list of patterns (route names or paths) which should be excluded from this group, *even if they match the rules in the `match` section*.
+
+For instance, supposing our routes are set up like this:
+
+```php
+Route::group(['domain' => 'v2-api.acme.co'], function () {
   Route::get('/apps', 'AppController@listApps')
     ->name('apps.list');
   Route::get('/apps/{id}', 'AppController@getApp')
@@ -94,147 +157,60 @@ Route::group(['domain' => 'api.acme.co'], function () {
     ->name('users.list');
   Route::get('/users/{id}', 'UserController@getUser')
     ->name('users.get');
+  Route::get('/status', 'StatusController@getStatus')
+    ->name('status');
 });
 
-Route::group(['domain' => 'public-api.acme.co'], function () {
-  Route::get('/stats', 'PublicController@getStats')
-    ->name('public.stats');
-});
-
-Route::group(['domain' => 'status.acme.co'], function () {
-  Route::get('/status', 'PublicController@getStatus')
-    ->name('status');
+Route::group(['domain' => 'api.acme.co'], function () {
+  Route::get('/getUsers', 'v1\UserController@getUsers')
+    ->name('v1.getUsers');
+  Route::get('/metrics', 'PublicController@getStats')
+    ->name('public.metrics');
 });
 ```
 
-### `match`
-In this section, you define the rules that will be used to determine what routes in your application fall into this group. There are three kinds of rules defined here (keys in the `match` array):
-
-#### `domains`
-This key takes an array of domain names as its value. Only routes which are defined on the domains specified here will be matched as part of this group. For instance, in our sample routes above, we may wish to apply different settings to documentation based on the domains. For instance, the routes on the `api.acme.co` domain need authentication, while those on the other domains do not. We can separate them into two groups like this:
+Supposing we only want to match endpoints on the `v2-api.acme.co` domain and we want to exclude the `/status` route but include the metrics route from `api.acme.co`, we could use this configuration:
 
 ```php
-<?php
-return [
-  //...,
-  
-  'routes' => [
-    [
-      'match' => [
-        'domains' => ['api.acme.co'],
-        'prefixes' => ['*'],
-      ],
-      'apply' => [
-        'headers' => [ 'Authorization' => 'Bearer {your-token}']
-      ]
+    'match' => [
+      'domains' => ['api.acme.co'],
+      'prefixes' => ['*'],
     ],
-    [
-      'match' => [
-        'domains' => ['public-api.acme.co', 'status.acme.co'],
-        'prefixes' => ['*'],
-      ],
-    ],
-  ],
-];
+    'include' => ['public.metrics'],
+    'exclude' => ['status'],
 ```
-The first group will match all routes on the 'api.acme.co' domain, and add a header 'Authorization: Bearer {your-token}' to the examples in the generated documentation. The second group will pick up the other routes. The Authorization header will not be added for those ones.
-
-You can use the `*` wildcard to match all domains (or as a placeholder in a pattern).
 
-#### `prefixes`
-The prefixes key is similar to the `domains` key, but is based on URL path prefixes (ie. what the part starts with, after the domain name). You could use prefixes to rewrite our example configuration above in a different way:
-
-```php
-<?php
-return [
-  //...,
-  
-  'routes' => [
-    [
-      'match' => [
-         'domains' => ['*'],
-         'prefixes' => ['users/*', 'apps/*'],
-       ],
-       'apply' => [
-         'headers' => [ 'Authorization' => 'Bearer {your-token}']
-       ]
-    ],
-    [
-      'match' => [
-         'domains' => ['*'],
-         'prefixes' => ['stats/*', 'status/*'],
-      ],
-    ],
-  ],
-];
+```eval_rst
+.. Tip:: You can use :code:`*` as a wildcard in :code:`domains, :code:`prefixes`, :code:`include` and :code:`exclude`. For instance, `:code:'exclude' => ['users/*']` will exclude all routes with URLs starting with 'users/'.
 ```
 
-This would achieve the same as the first configuration. As with domains, the `*` character is a wildcard. This means you can set up a ingle group to match all your routes by using `'domains' => ['*'], 'prefixes' => ['*']`. (This is set by default.)
-
-> The `domains` and `prefixes` keys are both required for all route groups.
+- `apply`: The `apply` section of the route group is where you specify any additional settings to be applied to those routes when generating documentation. There are a number of settings you can tweak here:
 
-#### `versions`
-> This section only applies if you're using Dingo Router
+  - `headers`: Any headers you specify here will be added to the headers shown in the example requests in your documentation. They will also be included in response calls. Headers are specified as key => value strings.
 
-When using Dingo's Router, all routes must be specified inside versions. This means that you must specify the versions to be matched along with the domains and prefixes when describing a route group. Note that wildcards in `versions` are not supported; you must list out all your versions explicitly. Example:
+  - `response_calls`: These are the settings that will be applied when making ["response calls"](documenting-endpoint-responses.html#generating-responses-automatically-via-response-calls). 
 
- ```php
-<?php
-return [
-  //...,
-  
-  'routes' => [
-    [
-      'match' => [
-        'domains' => ['*'],
-        'prefixes' => ['*'],
-        'versions' => ['v1', 'beta'], // only if you're using Dingo router
-      ],
-    ],
-  ],
-];
+```eval_rst
+.. Tip:: By splitting your routes into groups, you can apply different settings to different routes.
 ```
 
-### `include` and `exclude`
-The `include` key holds an array of patterns (route names or paths) which should be included in this group, *even if they do not match the rules in the `match` section*.
-The `exclude` key holds an array of patterns (route names or paths) which should be excluded from this group, *even if they match the rules in the `match` section*.
-
-Using our above sample routes, assuming you wanted to place the `users.list` route in the second group (no Authorization header), here's how you could do it:
+### `faker_seed`
+When generating example requests, this package uses the fzanninoto/faker package to generate random values. If you would like the package to generate the same example values for parameters on each run, set this to any number (eg. 1234).
 
-```php
-<?php
-return [
-  //...,
-  
-  'routes' => [
-    [
-      'match' => [
-        'domains' => ['api.acme.co'],
-        'prefixes' => ['*'],
-      ],
-      'exclude' => ['users.list'],
-      'apply' => [
-        'headers' => [ 'Authorization' => 'Bearer {your-token}']
-      ]
-    ],
-    [
-      'match' => [
-        'domains' => ['public-api.acme.co', 'status.acme.co'],
-        'prefixes' => ['*'],
-      ],
-      'include' => ['users.list'],
-    ],
-  ],
-];
+```eval_rst
+.. Tip:: Alternatively, you can set example values for parameters when [documenting them](documenting.html)).
 ```
 
-These values support wildcards and paths, so you can have `'exclude' => ['users/*']` to exclude all routes with URLs matching the pattern.
+### `routeMatcher`
+The route matcher class provides the algorithm that determines what routes should be documented. The default matcher used is the included `\Knuckles\Scribe\Matching\RouteMatcher::class`, and you can provide your own custom implementation if you wish to programmatically change the algorithm. The provided matcher should be an instance of the `RouteMatcherInterface`.
 
-### `apply`
-After defining the routes in `match` (and `include` or `exclude`), `apply` is where you specify the settings to be applied to those routes when generating documentation. There are a bunch of settings you can tweak here:
+### `fractal`
+This section only applies if you're using [transformers](https://fractal.thephpleague.com/transformers/) for your API (via the league/fractal package), and documenting responses with `@transformer` and `@transformerCollection`. Here, you configure how responses are transformed.
 
-#### `headers`
-Like we've demonstrated above, any headers you specify here will be added to the headers shown in the example requests in your documentation. They will also be included in ["response calls"](documenting.html#generating-responses-automatically). Headers are specified as key => value strings.
+- `serializer`: If you are using a custom serializer with league/fractal,  you can specify it here. league/fractal comes with the following serializers:
+  - `\League\Fractal\Serializer\ArraySerializer::class`
+  - `\League\Fractal\Serializer\DataArraySerializer::class`
+  - `\League\Fractal\Serializer\JsonApiSerializer::class`
 
-#### `response_calls`
-These are the settings that will be applied when making ["response calls"](documenting.html#generating-responses-automatically). See the linked section for details.
+  Leave this as `null` to use no serializer or return a simple JSON.
+     

docs/plugins.md

@@ -62,7 +62,7 @@ There are a number of strategies included with the package, so you don't have to
 ## Creating a strategy
 To create a strategy, create a class that extends `\Knuckles\Scribe\Extracting\Strategies\Strategy`. You can do this by running the `scribe:strategy` command. By default, this will place the strategy in your `App\Docs\Strategies` namespace. The first argument to `scribe:strategy` is the name of the strategy, the second is the stage it belongs to.
 
-```sh
+```bash
 php artisan scribe:strategy AddPaginationParameters queryParameters
 ```
 

resources/views/partials/example-requests/python.blade.php

@@ -2,7 +2,7 @@
 import requests
 import json
 
-url = '{{ rtrim($baseUrl, '/') }}/{{ ltrim($route['boundUri'], '/') }}'
+url = '{{ rtrim($baseUrl, '/') }}/{{ $route['boundUri'] }}'
 @if(count($route['fileParameters']))
 files = {
 @foreach($route['fileParameters'] as $name => $file)