Reviewed documentation for publication

- Renamed from `zend.uri.md` to `usage.md`
- Split docs into an intro and a usage chapter
- Reviewed for content and formatting
- Added mkdocs configuration

Author: weierophinney

README.md

@@ -3,11 +3,10 @@
 [![Build Status](https://secure.travis-ci.org/zendframework/zend-uri.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-uri)
 [![Coverage Status](https://coveralls.io/repos/zendframework/zend-uri/badge.svg?branch=master)](https://coveralls.io/r/zendframework/zend-uri?branch=master)
 
-`Zend\Uri` is a component that aids in manipulating and validating Uniform
-Resource Identifiers ([URIs](http://www.ietf.org/rfc/rfc3986.txt)). `Zend\Uri`
-exists primarily to service other components, such as `Zend\Http`, but is also
-useful as a standalone utility.
-
+zend-uri aids in manipulating and validating Uniform Resource Identifiers
+([URIs](http://www.ietf.org/rfc/rfc3986.txt)). zend-uri exists primarily to
+assist other components, such as zend-http, but is also useful as a standalone
+utility.
 
 - File issues at https://github.com/zendframework/zend-uri/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-uri
+- Documentation is at https://zendframework.github.io/zend-uri/

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-uri</h1>
+    
+    <p>Object oriented interface to URIs, with facilities for validation.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-uri</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

doc/book/intro.md

@@ -0,0 +1,14 @@
+# Introduction
+
+zend-uri aids in manipulating and validating [Uniform 
+Resource Identifiers](http://www.w3.org/Addressing/)
+([URIs](http://www.ietf.org/rfc/rfc3986.txt)). zend-uri exists primarily
+to assist other components, such as
+[zend-http](https://zendframework.github.io/zend-http/), but is also useful as a
+standalone utility.
+
+URIs always begin with a scheme, followed by a colon. The construction of the
+many different schemes varies significantly. The zend-uri component provides the
+`Zend\Uri\UriFactory` that returns an instance of the appropriate class
+implementing `Zend\Uri\UriInterface` for the given scheme (assuming the factory
+can locate one).

doc/book/zend.uri.md renamed to doc/book/usage.md

@@ -1,18 +1,4 @@
-# Zend\\Uri
-
-## Overview
-
-`Zend\Uri` is a component that aids in manipulating and validating [Uniform 
-Resource Identifiers](http://www.w3.org/Addressing/)
-([URIs](http://www.ietf.org/rfc/rfc3986.txt)). `Zend\Uri` exists primarily
-to service other components, such as `Zend\Http`, but is also useful as a
-standalone utility.
-
-*URI*s always begin with a scheme, followed by a colon. The construction of the
-many different schemes varies significantly. The `Zend\Uri` component provides
-the `Zend\Uri\UriFactory` that returns a class implementing the
-`Zend\Uri\UriInterface` which specializes in the scheme if such a class is
-registered with the Factory.
+# Usage
 
 ## Creating a New URI
 
@@ -29,38 +15,41 @@ $uri = Zend\Uri\UriFactory::factory('http:');
 // $uri instanceof Zend\Uri\UriInterface
 ```
 
-To create a new *URI* from scratch, pass only the scheme followed by a colon to
+To create a new URI from scratch, pass only the scheme followed by a colon to
 `Zend\Uri\UriFactory::factory()`. If an unsupported scheme is passed and no
 scheme-specific class is specified, a
 `Zend\Uri\Exception\InvalidArgumentException` will be thrown.
 
-If the scheme or *URI* passed is supported, `Zend\Uri\UriFactory::factory()`
-will return a class implementing `Zend\Uri\UriInterface` that specializes in the
-scheme to be created.
+If the scheme or URI passed is supported, `Zend\Uri\UriFactory::factory()` will
+return a class implementing `Zend\Uri\UriInterface` that specializes in the
+scheme referenced.
 
-> ### Note
-At the time of writing, `Zend\Uri` provides built-in support for the following
-schemes: HTTP, HTTPS, MAILTO and FILE
+> ### Supported schemes
+>
+> At the time of writing, zend-uri provides built-in support for the following
+> schemes only: HTTP, HTTPS, MAILTO and FILE.
 
 ### Creating a New Custom-Class URI
 
 You can specify a custom class to be used when using the `Zend\Uri\UriFactory`
-by registering your class with the Factory using
-`Zend\Uri\UriFactory::registerScheme()` which takes the scheme as first
-parameter. This enables you to create your own *URI*-class and instantiate new
-*URI* objects based on your own custom classes.
+by registering your class with the `UriFactory` using
+`Zend\Uri\UriFactory::registerScheme($scheme, $class)`.  This enables you to
+create your own URI class and instantiate new URI objects based on your own
+custom classes.
 
 The 2nd parameter passed to `Zend\Uri\UriFactory::registerScheme()` must be a
 string with the name of a class implementing `Zend\Uri\UriInterface`. The class
 must either be already loaded, or be loadable by the autoloader.
 
 #### Creating a URI using a custom class
 
+The following registers the `ftp` scheme with a custom URI class:
+
 ```php
-// Create a new 'ftp' URI based on a custom class
+use MyNamespace\MyClass;
 use Zend\Uri\UriFactory
 
-UriFactory::registerScheme('ftp', 'MyNamespace\MyClass');
+UriFactory::registerScheme('ftp', MyClass::class);
 
 $ftpUri = UriFactory::factory(
     'ftp://[email protected]/path/file'
@@ -72,135 +61,126 @@ $ftpUri = UriFactory::factory(
 
 ## Manipulating an Existing URI
 
-To manipulate an existing *URI*, pass the entire *URI* as string to
-`Zend\Uri\UriFactory::factory()`.
+To manipulate an existing URI, pass the entire URI as a string to
+`Zend\Uri\UriFactory::factory()`, and then manipulate the instance returned.
 
 ### Manipulating an Existing URI with Zend\\Uri\\UriFactory::factory()
 
 ```php
+use Zend\Uri\UriFactory;
+
 // To manipulate an existing URI, pass it in.
-$uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
+$uri = UriFactory::factory('http://www.zend.com');
 
 // $uri instanceof Zend\Uri\UriInterface
 ```
 
-The *URI* will be parsed and validated. If it is found to be invalid, a
+The URI will be parsed and validated. If it is found to be invalid, a
 `Zend\Uri\Exception\InvalidArgumentException` will be thrown immediately.
 Otherwise, `Zend\Uri\UriFactory::factory()` will return a class implementing
 `Zend\Uri\UriInterface` that specializes in the scheme to be manipulated.
 
 ## Common Instance Methods
 
 The `Zend\Uri\UriInterface` defines several instance methods that are useful for
-working with any kind of *URI*.
+working with any kind of URI.
 
 ### Getting the Scheme of the URI
 
-The scheme of the *URI* is the part of the *URI* that precedes the colon. For
+The scheme of the URI is the part of the URI that precedes the colon. For
 example, the scheme of `http://[email protected]/my/path?query#token` is
 'http'.
 
-#### Getting the Scheme from a Zend\\Uri\\UriInterface Object
-
 ```php
 $uri = Zend\Uri\UriFactory::factory('mailto:[email protected]');
 
 $scheme = $uri->getScheme();  // "mailto"
 ```
 
-The `getScheme()` instance method returns only the scheme part of the *URI*
-object.
+The `getScheme()` instance method returns only the scheme part of the URI
+object (not the separator).
 
 ### Getting the Userinfo of the URI
 
-The userinfo of the *URI* is the optional part of the *URI* that follows the
+The userinfo of the URI is the optional part of the URI that follows the
 colon and comes before the host-part. For example, the userinfo of
 `http://[email protected]/my/path?query#token` is 'johndoe'.
 
-#### Getting the Username from a Zend\Uri\UriInterface Object
-
 ```php
 $uri = Zend\Uri\UriFactory::factory('mailto:[email protected]');
 
 $scheme = $uri->getUserinfo();  // "john.doe"
 ```
 
-The `getUserinfo()` method returns only the userinfo part of the *URI* object.
+The `getUserinfo()` method returns only the userinfo part of the URI object.
 
 ### Getting the host of the URI
 
-The host of the *URI* is the optional part of the *URI* that follows the
+The host of the URI is the optional part of the URI that follows the
 user-part and comes before the path-part. For example, the host of
 `http://[email protected]/my/path?query#token` is 'example.com'.
 
-#### Getting the host from a Zend\\Uri\\UriInterface Object
-
 ```php
 $uri = Zend\Uri\UriFactory::factory('mailto:[email protected]');
 
 $scheme = $uri->getHost();  // "example.com"
 ```
 
-The `getHost()` method returns only the host part of the *URI* object.
+The `getHost()` method returns only the host part of the URI object.
 
 ### Getting the port of the URI
 
-The port of the *URI* is the optional part of the *URI* that follows the
-host-part and comes before the path-part. For example, the host of
-`http://[email protected]:80/my/path?query#token` is '80'. The *URI*-class can
-define default-ports that can be returned when no port is given in the *URI*.
-
-#### Getting the port from a Zend\\Uri\\UriInterface Object
+The port of the URI is the optional part of the URI that follows the host-part
+and comes before the path-part. For example, the host of
+`http://[email protected]:80/my/path?query#token` is '80'.
 
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://example.com:8080');
 
 $scheme = $uri->getPort();  // "8080"
 ```
 
-#### Getting a default port from a Zend\\Uri\\UriInterface Object
+Concrete URI instances can define default ports that can be returned when no
+port is given in the URI:
 
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://example.com');
 
 $scheme = $uri->getPort();  // "80"
 ```
 
-The `getHost()` method returns only the port part of the *URI* object.
+The `getHost()` method returns only the port part of the URI object.
 
 ### Getting the path of the URI
 
-The path of the *URI* is the mandatory part of the *URI* that follows the port
+The path of the URI is a mandatory part of the URI that follows the port
 and comes before the query-part. For example, the path of
 `http://[email protected]:80/my/path?query#token` is '/my/path'.
 
-#### Getting the path from a Zend\\Uri\\UriInterface Object
-
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 
 $scheme = $uri->getPath();  // "/my/path"
 ```
 
-The `getPath()` method returns only the path of the *URI* object.
+The `getPath()` method returns only the path of the URI object.
 
 ### Getting the query-part of the URI
 
-The query-part of the *URI* is the optional part of the *URI* that follows the
+The query-part of the URI is an optional part of the URI that follows the
 path and comes before the fragment. For example, the query of
-`http://[email protected]:80/my/path?query#token` is 'quer'.
-
-#### Getting the query from a Zend\\Uri\\UriInterface Object
+`http://[email protected]:80/my/path?query#token` is 'query'.
 
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 
 $scheme = $uri->getQuery();  // "a=b&c=d"
 ```
 
-The `getQuery()` method returns only the query-part of the *URI* object.
+The `getQuery()` method returns only the query-part of the URI object.
 
-#### Getting the query as array from a Zend\\Uri\\UriInterface Object
+The query string often contains key=value pairs and therefore can be split into an
+associative array. This array can be retrieved using `getQueryAsArray()`:
 
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
@@ -212,28 +192,23 @@ $scheme = $uri->getQueryAsArray();
 // ]
 ```
 
-The query-part often contains key=value pairs and therefore can be split into an
-associative array. This array can be retrieved using `getQueryAsArray()`.
-
 ### Getting the fragment-part of the URI
 
-The fragment-part of the *URI* is the optional part of the *URI* that follows
+The fragment-part of the URI is an optional part of the URI that follows
 the query. For example, the fragment of
 `http://[email protected]:80/my/path?query#token` is 'token'.
 
-#### Getting the fragment from a Zend\\Uri\\UriInterface Object
-
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 
 $scheme = $uri->getFragment();  // "token"
 ```
 
-The `getFragment()` method returns only the fragment-part of the *URI* object.
+The `getFragment()` method returns only the fragment-part of the URI object.
 
 ### Getting the Entire URI
 
-#### Getting the Entire URI from a Zend\\Uri\\UriInterface Object
+The `toString()` method returns the string representation of the entire *URI*.
 
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
@@ -244,27 +219,23 @@ echo $uri->toString();  // "http://www.zend.com"
 echo (string) $uri;     // "http://www.zend.com"
 ```
 
-The `toString()` method returns the string representation of the entire *URI*.
-
-The `Zend\Uri\UriInterface` defines also a magic `__toString()` method that
-returns the string representation of the *URI* when the Object is cast to a
+The `Zend\Uri\UriInterface` defines also the magic `__toString()` method that
+returns the string representation of the URI when the object is cast to a
 string.
 
-### Validating the URI
+## Validating the URI
 
-When using `Zend\Uri\UriFactory::factory()` the given *URI* will always be
+When using `Zend\Uri\UriFactory::factory()`, the given URI will always be
 validated and a `Zend\Uri\Exception\InvalidArgumentException` will be thrown
-when the *URI* is invalid. However, after the `Zend\Uri\UriInterface` is
-instantiated for a new *URI* or an existing valid one, it is possible that the
-*URI* can later become invalid after it is manipulated.
-
-#### Validating a ZendUri* Object
+when the URI is invalid. However, after the `Zend\Uri\UriInterface` is
+instantiated for a new URI or an existing valid one, it is possible that the URI
+can later become invalid after it is manipulated.
 
 ```php
 $uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
 
 $isValid = $uri->isValid();  // TRUE
 ```
 
-The `isValid()` instance method provides a means to check that the *URI* object
-is still valid.
+The `isValid()` instance method provides a means to check that the URI object
+is still valid.

mkdocs.yml

@@ -0,0 +1,10 @@
+docs_dir: doc/book
+site_dir: doc/html
+pages:
+    - index.md
+    - Intro: intro.md
+    - Usage: usage.md
+site_name: zend-uri
+site_description: zend-uri
+repo_url: 'https://github.com/zendframework/zend-uri'
+copyright: 'Copyright (c) 2016 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'