Split docs into three pages

- Intro for package introduction
- Configuration
- Usage

Author: weierophinney

docs/book/v1/config.md

@@ -0,0 +1,41 @@
+# Configuration
+
+To use the adapter, you will need to provide the following configuration:
+
+- A valid zend-expressive-authentication `UserRepositoryInterface` service in
+  your DI container. This service will perform the actual work of validating the
+  supplied credentials.
+
+- An HTTP Basic **realm**. This may be an arbitrary value, but is [required by
+  the specification](https://tools.ietf.org/html/rfc7617#section-2).
+
+- A response factory. If you are using Expressive, this is already configured
+  for you.
+
+As an example of configuration:
+
+```php
+// config/autoload/authentication.global.php
+
+use Zend\Expressive\Authentication\AdapterInterface;
+use Zend\Expressive\Authentication\Basic\BasicAccess;
+use Zend\Expressive\Authentication\UserRepositoryInterface;
+use Zend\Expressive\Authentication\UserRepository\PdoDatabase;
+
+return [
+    'dependencies' => [
+        'aliases' => [
+            // Use the default PdoDatabase user repository. This assumes
+            // you have configured that service correctly.
+            UserRepositoryInterface::class => PdoDatabase::class,
+
+            // Tell zend-expressive-authentication to use the BasicAccess
+            // adapter:
+            AdapterInterface::class => BasicAccess::class,
+        ],
+    ],
+    'authentication' => [
+        'realm' => 'api',
+    ],
+];
+```

docs/book/v1/intro.md

@@ -16,93 +16,3 @@ the supplied credentials**.
 > Since HTTP Basic transmits the credentials via the URL, it should only be used
 > within trusted networks, and never in public-facing sites, as the URL can be
 > sniffed by MITM proxies.
-
-## Configuration
-
-To use the adapter, you will need to provide the following configuration:
-
-- A valid zend-expressive-authentication `UserRepositoryInterface` service in
-  your DI container. This service will perform the actual work of validating the
-  supplied credentials.
-
-- An HTTP Basic **realm**. This may be an arbitrary value, but is [required by
-  the specification](https://tools.ietf.org/html/rfc7617#section-2).
-
-- A response factory. If you are using Expressive, this is already configured
-  for you.
-
-As an example of configuration:
-
-```php
-// config/autoload/authentication.global.php
-
-use Zend\Expressive\Authentication\AdapterInterface;
-use Zend\Expressive\Authentication\Basic\BasicAccess;
-use Zend\Expressive\Authentication\UserRepositoryInterface;
-use Zend\Expressive\Authentication\UserRepository\PdoDatabase;
-
-return [
-    'dependencies' => [
-        'aliases' => [
-            // Use the default PdoDatabase user repository. This assumes
-            // you have configured that service correctly.
-            UserRepositoryInterface::class => PdoDatabase::class,
-
-            // Tell zend-expressive-authentication to use the BasicAccess
-            // adapter:
-            AdapterInterface::class => BasicAccess::class,
-        ],
-    ],
-    'authentication' => [
-        'realm' => 'api',
-    ],
-];
-```
-
-## Usage
-
-Whenever you need an authenticated user, you can place the
-zend-expressive-authentication `AuthenticationMiddleware` in your pipeline.
-
-### Globally
-
-If you need all routes to use authentication, add it globally.
-
-```php
-// In config/pipeline.php, within the callback:
-
-$app->pipe(Zend\Expressive\Authentication\AuthenticationMiddleware::class);
-```
-
-### For an entire sub-path
-
-If you need all routes that begin with a particular sub-path to require
-authentication, use [path-segregation](https://docs.zendframework.com/zend-stratigility/v3/api/#path):
-
-```php
-// In config/pipeline.php.
-// In the import statements:
-use Zend\Expressive\Authentication\AuthenticationMiddleware;
-
-// In the callback:
-$app->pipe('/api', $factory->path(
-    $factory->prepare(AuthenticationMiddleware::class)
-));
-```
-
-### For a specific route
-
-If you want to restrict access for a specific route, create a [route-specific
-middleware pipeline](https://docs.zendframework.com/zend-expressive/v3/cookbook/route-specific-pipeline/):
-
-```php
-// In config/routes.php, in the callback:
-
-$app->get(
-    '/path/requiring/authentication',
-    [
-        Zend\Expressive\Authentication\AuthenticationMiddleware::class,
-        HandlerRequiringAuthentication::class, // use your own handler here
-    ]
-);
-```

docs/book/v1/usage.md

@@ -0,0 +1,47 @@
+# Usage
+
+Whenever you need an authenticated user, you can place the
+zend-expressive-authentication `AuthenticationMiddleware` in your pipeline.
+
+## Globally
+
+If you need all routes to use authentication, add it globally.
+
+```php
+// In config/pipeline.php, within the callback:
+
+$app->pipe(Zend\Expressive\Authentication\AuthenticationMiddleware::class);
+```
+
+## For an entire sub-path
+
+If you need all routes that begin with a particular sub-path to require
+authentication, use [path-segregation](https://docs.zendframework.com/zend-stratigility/v3/api/#path):
+
+```php
+// In config/pipeline.php.
+// In the import statements:
+use Zend\Expressive\Authentication\AuthenticationMiddleware;
+
+// In the callback:
+$app->pipe('/api', $factory->path(
+    $factory->prepare(AuthenticationMiddleware::class)
+));
+```
+
+## For a specific route
+
+If you want to restrict access for a specific route, create a [route-specific
+middleware pipeline](https://docs.zendframework.com/zend-expressive/v3/cookbook/route-specific-pipeline/):
+
+```php
+// In config/routes.php, in the callback:
+
+$app->get(
+    '/path/requiring/authentication',
+    [
+        Zend\Expressive\Authentication\AuthenticationMiddleware::class,
+        HandlerRequiringAuthentication::class, // use your own handler here
+    ]
+);
+```

mkdocs.yml

@@ -3,6 +3,8 @@ site_dir: docs/html
 pages:
     - Home: index.md
     - Introduction: v1/intro.md
+    - Configuration: v1/config.md
+    - Usage: v1/usage.md
     - "_hidden-legacy-page-links":
       - "_intro": intro.md
 site_name: zend-expressive-authentication-basic