wip

Author: mpociot

docs/Makefile

@@ -0,0 +1,4 @@
+---
+packageName: Laravel API Documentation Generator
+githubUrl: https://github.com/mpociot/laravel-api-doc-generator
+---

docs/_index.md

@@ -0,0 +1,4 @@
+---
+title: Extending
+order: 2
+---

docs/conf.py

@@ -1,3 +1,7 @@
+---
+title: Plugins
+order: 1
+---
 # Extending functionality with plugins
 You can use plugins to alter how the Generator fetches data about your routes. For instance, suppose all your routes have a body parameter `organizationId`, and you don't want to annotate this with `@queryParam` on each method. You can create a plugin that adds this to all your body parameters. Let's see how to do this.
 
@@ -29,8 +33,6 @@ The `__invoke` method of the strategy is where you perform your actions and retu
  Here's what your strategy in our example would look like:
 
  ```php
-<?php
-
 use Illuminate\Routing\Route;
 use Mpociot\ApiDoc\Extracting\Strategies\Strategy;
 

docs/extending/_index.md

@@ -0,0 +1,4 @@
+---
+title: Getting Started
+order: 1
+---

docs/plugins.md renamed to docs/extending/plugins.md

@@ -1,75 +1,86 @@
+---
+title: Configuration
+order: 2
+---
 # Configuration
 
-Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.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).
+Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php` file. 
 
-## `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/apidoc` folder, so you can add routing and authentication.
+If you aren't sure what an option does, it's best to leave it set to the default.
+
+## 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/apidoc` folder, so you can add routing and authentication to your liking.
 
 > In both instances, the source markdown file will be generated in `resources/docs/source`.
 
-## `laravel`
+### 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.
 
-### `autoload`
-Set this to `true` if you want the documentation endpoint to be automatically set up for you. Default: `false` (*note that this will change in the next major release*)
+### autoload
+Set this to `true` if you want the documentation endpoint to be automatically set up for you. Default: `false`
 
 You may, of course, use your own routing instead of using `autoload`.
 
-### `docs_url`
+### docs_url
 The path for the documentation endpoint (if `autoload` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/doc.json`). Default: `/doc`
 
 > Note: There is currently a known issue with using `/docs` as the path for `laravel` docs. You should not use it, as it conflicts with the folder structure in the `public` folder and may confuse the webserver.
 
-### `middleware`
+## middleware
 Here, you can specify middleware to be attached to the documentation endpoint (if `autoload` is true).
 
-## `router`
+## router
 The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)
 
-## `base_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').
 
-## `postman`
+## 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/apidoc/collection.json`. The `ApiDoc::routes()` helper will add a `/docs.json` endpoint to fetch it..
 
-### `enabled`
+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/apidoc/collection.json`. The `ApiDoc::routes()` helper will add a `/docs.json` endpoint to fetch it..
+
+### enabled
 Whether or not to generate a Postman API collection. Default: **true**
 
-### `name`
+### name
 The name for the exported Postman collection. If you leave this as null, this package will default to `config('app.name')." API"`.
 
-### `description`
+### description
 The description for the generated Postman collection.
 
-## `logo`
+## 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'
 ```
 
 If you want to use this, please note that the image size must be 230 x 52.
 
-## `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"**.
+## default_group
+When [documenting your api](/docs/laravel-api-doc-generator/getting-started/documenting-your-api), 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"**.
 
-## `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"]` 
+## 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](/docs/laravel-api-doc-generator/getting-started/generating-documentation)). 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))
+##  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.](/docs/laravel-api-doc-generator/getting-started/documenting-your-api))
 
-## `routeMatcher`
+## routeMatcher
 The route matcher class provides the algorithm that determines what routes should be documented. The default matcher used is the included `\Mpociot\ApiDoc\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.
+## 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.
 
 > Note: using transformers requires league/fractal package. Run `composer require league/fractal to install
 
+
 ### 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
@@ -78,16 +89,14 @@ If you are using a custom serializer with league/fractal,  you can specify it he
 
 Leave this as null to use no serializer or return a simple JSON.
 
-## `routes`
+## routes
 The `routes` section is an array of items, describing what routes in your application that should have documentation generated for them. 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.
 
 > Note: This package does not work with Closure-based routes. If you want your route to be captured by this package, you need a controller.
 
 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:
 
 ```php
-<?php
-
 Route::group(['domain' => 'api.acme.co'], function () {
   Route::get('/apps', 'AppController@listApps')
     ->name('apps.list');
@@ -112,14 +121,13 @@ Route::group(['domain' => 'status.acme.co'], function () {
 });
 ```
 
-### `match`
+### 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`
+### 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:
 
 ```php
-<?php
 return [
   //...,
 
@@ -146,11 +154,10 @@ The first group will match all routes on the 'api.acme.co' domain, and add a hea
 
 You can use the `*` wildcard to match all domains (or as a placeholder in a pattern).
 
-#### `prefixes`
+### 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 [
   //...,
 
@@ -178,13 +185,12 @@ This would achieve the same as the first configuration. As with domains, the `*`
 
 > The `domains` and `prefixes` keys are both required for all route groups.
 
-#### `versions`
+### versions
 > This section only applies if you're using Dingo Router
 
 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:
 
  ```php
-<?php
 return [
   //...,
 
@@ -200,14 +206,15 @@ return [
 ];
 ```
 
-### `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*.
+### 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:
 
 ```php
-<?php
 return [
   //...,
 
@@ -235,11 +242,11 @@ return [
 
 These values support wildcards and paths, so you can have `'exclude' => ['users/*']` to exclude all routes with URLs matching the pattern.
 
-### `apply`
+### 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:
 
-#### `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.
+### 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"](/docs/laravel-api-doc-generator/getting-started/documenting-your-api). Headers are specified as key => value strings.
 
-#### `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.
+### response_calls
+These are the settings that will be applied when making ["response calls"](/docs/laravel-api-doc-generator/getting-started/documenting-your-api). See the linked section for details.

docs/getting-started/_index.md

@@ -1,3 +1,7 @@
+---
+title: Documenting Your API
+order: 4
+---
 # Documenting Your API
 This package generates documentation from your code using mainly annotations (in doc block comments).
 
@@ -45,7 +49,7 @@ class UserController extends Controller
 
 **Result:** 
 
-![Doc block result](http://headsquaredsoftware.co.uk/images/api_generator_docblock.png)
+![Doc block result](/img/api_generator_docblock.png)
 
 ## Specifying request parameters
 To specify a list of valid parameters your API route accepts, use the `@urlParam`, `@bodyParam` and `@queryParam` annotations.
@@ -92,12 +96,6 @@ public function listPosts()
 
 They will be included in the generated documentation text and example requests.
 
-**Result:**
-
-![](./../body_params_1.png)
-
-![](./../body_params_2.png)
-
 ### Example parameters
 For each parameter in your request, this package will generate a random value to be used in the example requests. If you'd like to specify an example value, you can do so by adding `Example: your-example` to the end of your description. For instance:
 

docs/config.md renamed to docs/getting-started/configuration.md

@@ -1,10 +1,13 @@
+---
+title: Generating Documentation
+order: 5
+---
 # Generating Documentation
 
 To generate your API documentation, use the `apidoc:generate` artisan command.
 
 ```sh
 php artisan apidoc:generate
-
 ```
 
 It will generate documentation using your specified configuration. The documentation will be generated as static HTML and CSS assets within the specified output folder.