Merge pull request #45 from froschdesign/hotfix/docs

michalbundyra · michalbundyra · commit 08a78d4c20ad · 2019-11-03T09:03:32.000Z
Updates for documentation
diff --git a/docs/book/adapter.md b/docs/book/adapter.md
@@ -1,4 +1,4 @@
-# Console adapters
+# Console Adapters
 
 zend-console's console abstraction layer works around various bugs and limitations
 in operating systems, including:
diff --git a/docs/book/getopt/configuration.md b/docs/book/getopt/configuration.md
@@ -1,4 +1,4 @@
-# Configuring Zend\\Console\\Getopt
+# Configuration
 
 ## Adding Option Rules
 
diff --git a/docs/book/getopt/fetching.md b/docs/book/getopt/fetching.md
@@ -60,7 +60,7 @@ Alternatively, you can use the property overloading via the magic `__isset()` an
 `__get()` methods, allowing you to test for and retrieve values as if they were
 property names.
 
-### Using property overloading
+### Using property Overloading
 
 ```php
 $opts = new Zend\Console\Getopt('abp:');
@@ -70,7 +70,7 @@ if (isset($opts->b)) {
 $p_parameter = $opts->p; // null if not set
 ```
 
-> ### Using aliases
+> ### Using Aliases
 >
 > If your options are declared with aliases, you may use any of the aliases for
 > an option when retrieving its value.
diff --git a/docs/book/getopt/intro.md b/docs/book/getopt/intro.md
@@ -1,4 +1,4 @@
-# Zend\\Console\\Getopt
+# Introduction
 
 The `Zend\Console\Getopt` class helps command-line applications to parse their
 options and arguments.
diff --git a/docs/book/getopt/rules.md b/docs/book/getopt/rules.md
@@ -1,4 +1,4 @@
-# Declaring Getopt Rules
+# Declaring Rules
 
 The constructor for the `Zend\Console\Getopt` class takes from one to three
 arguments. The first argument declares which options are supported by your
diff --git a/docs/book/index.html b/docs/book/index.html
diff --git a/docs/book/index.md b/docs/book/index.md
diff --git a/docs/book/index.md b/docs/book/index.md
@@ -0,0 +1,13 @@
+> ### Deprecated!
+>
+> Both the zend-console and the [zend-mvc-console](https://docs.zendframework.com/zend-mvc-console/)
+> components will likely not be maintained long-term, as there are more complete
+> implementations available elsewhere. We strongly urge developers to start
+> migrating their console tooling to use other libraries, such as
+> [symfony/console](https://github.com/symfony/console).
+
+## Installation
+
+```bash
+$ composer require zendframework/zend-console
+```
diff --git a/docs/book/intro.md b/docs/book/intro.md
@@ -1,12 +1,4 @@
-# Introduction to zend-console
-
-> ### Deprecated
->
-> Both the zend-console and the [zend-mvc-console](https://docs.zendframework.com/zend-mvc-console/)
-> components will likely not be maintained long-term, as there are more complete
-> implementations available elsewhere. We strongly urge developers to start
-> migrating their console tooling to use other libraries, such as
-> [symfony/console](https://github.com/symfony/console).
+# Introduction
 
 zend-console provides both generic support for routable console applications, as
 well as the basis for adding console support to zend-mvc-based applications.
@@ -71,7 +63,7 @@ the action `resetpassword` of `Application\Controller\IndexController`.
 
 First we need to create a **route definition**:
 
-```
+```text
 user resetpassword <userEmail>
 ```
 
@@ -80,15 +72,15 @@ This simple route definition expects exactly three arguments: the literal
 "userEmail". Let's assume we also accept one optional parameter to enable
 verbose operation:
 
-```
+```text
 user resetpassword [--verbose|-v] <userEmail>
 ```
 
 The modified console route above expects the same three arguments from our
 original example, but will also recognise an optional `--verbose` flag, or its
 shorthand version, `-v`.
 
-> ### Flag order
+> ### Flag Order
 >
 > The order of flags is ignored by zend-console. Flags can appear before
 > positional parameters, after them, or anywhere in between. The order of
@@ -147,7 +139,7 @@ return [
 ;
 ```
 
-## Handling console requests
+## Handling Console Requests
 
 When a user runs our application from the command line and arguments match our
 console route, the specified controller will be instantiated, and the specified
@@ -157,7 +149,6 @@ As such, let's add the `resetpassword` action to our
 `Application\Controller\IndexController`:
 
 ```php
-<?php
 namespace Application\Controller;
 
 use RuntimeException;
@@ -214,7 +205,7 @@ The above creates `resetpasswordAction()`, which:
 - performs work based on the arguments;
 - and finally returns a simple string to display to the user via the console.
 
-## Adding console usage info
+## Adding Console Usage Info
 
 Console applications commonly display usage information when run without
 arguments. The combination of zend-console and zend-mvc enables this out of the
@@ -224,8 +215,6 @@ modules for console usage information they expose.
 Let's modify our `Application\Module` to provide usage info:
 
 ```php
-<?php
-
 namespace Application;
 
 use Zend\ModuleManager\Feature\AutoloaderProviderInterface;
diff --git a/docs/book/mvc/controllers.md b/docs/book/mvc/controllers.md
@@ -1,10 +1,10 @@
-# Console-aware controllers
+# Console-Aware Controllers
 
 When using the zend-mvc integration with zend-console, a matched route results
 in dispatch of an action controller. In this chapter we will learn how ZF2
 Controllers can interact with and return output to console window.
 
-## Handling console requests
+## Handling Console Requests
 
 Console requests are very similar to HTTP requests. In fact, they implement a
 common interface and are created at the same time in the MVC workflow. [Console
@@ -102,7 +102,7 @@ We fetch the console request, read parameters, and load users from our
 (theoretical) users service.  In order to make this method functional, we'll
 have to display the result in the console window.
 
-## Sending output to the console
+## Sending Output to the Console
 
 The simplest way for our controller to display data in the console window is to
 return a string. Let's modify our example to output a list of users:
@@ -155,7 +155,7 @@ application.
 If any users are found, we loop through each to prepare a listing, which we then
 return from the action for display in the console.
 
-## Are we in a console?
+## Are we in a Console?
 
 Sometimes we might need to check if our method is being called from a console or
 from a web request. This is useful to block certain methods from running in the
@@ -188,7 +188,7 @@ class IndexController extends AbstractActionController
 }
 ```
 
-> ### Use routing to protect methods
+> ### Use Routing to protect Methods
 >
 > You do not need to secure all your controllers and methods from console
 > requests. Controller actions will **only be invoked** when at least one
@@ -243,13 +243,13 @@ class IndexController extends AbstractActionController
 > adapter, allowing you to use prompts, send output (including colorized output),
 > and more.
 
-## Reading values from console parameters
+## Reading Values from Console Parameters
 
 There are several types of parameters recognized by the Console component, all
 of which are described in the [console routing chapter](../routes.md). Here, we'll
 focus on how to retrieve values from distinct parameters and flags.
 
-### Positional parameters
+### Positional Parameters
 
 After a route matches, we can access both **literal parameters** and **value
 parameters** via the `$request` instance, using the `getParam()` method.
diff --git a/docs/book/mvc/modules.md b/docs/book/mvc/modules.md
@@ -1,4 +1,4 @@
-# Console-aware modules
+# Console-Aware Modules
 
 zend-mvc integrates with zend-console; the integration also works with modules
 loaded with the
diff --git a/docs/book/mvc/routing.md b/docs/book/mvc/routing.md
@@ -54,21 +54,21 @@ expects two parameters: `foo` and `bar`. If user puts these in a console,
 `Application\Controller\IndexController::passwordAction()` action will be
 invoked.
 
-## Route types
+## Route Types
 
 In the last example of the previous section, we noted that configuration for a
 given route can accept a `type` argument. This refers to the route type (which
 maps to a class) to use when creating the route instance. zend-mvc defines
 several types.
 
-### Simple route
+### Simple Route
 
 `Zend\Mvc\Router\Console\Simple` is a factory for zend-console's
 `DefaultRouteMatcher`, and decorates it to work with the zend-mvc routing
 system. See the section on [the default route matcher](../routes.md#the-default-route-matcher)
 for details on route strings and available configuration to provide.
 
-### Catchall route
+### Catchall Route
 
 This special route will catch all console requests, regardless of the parameters provided.
 
diff --git a/docs/book/prompts.md b/docs/book/prompts.md
@@ -1,4 +1,4 @@
-# Console prompts
+# Console Prompts
 
 In addition to the console abstraction layer, zend-console provides numerous
 convenience classes for interacting with the user in a console environment. This
diff --git a/docs/book/routes.md b/docs/book/routes.md
@@ -1,10 +1,10 @@
-# Console routes and routing
+# Routes
 
 A powerful feature the zend-console component exposes is *routing*. Routing
 reads the command line arguments and matches them to criteria; if the criteria
 matches, it then returns a list of matched parameters and flags.
 
-> ## Handling routing results
+> ### Handling routing results
 >
 > zend-console exposes routing via the `Zend\Console\RouteMatcher\DefaultRouteMatcher`
 > class, allowing you to create standalone routable console applications.
@@ -42,7 +42,7 @@ the routing implementation as an array; the routing implementation will then
 return either a `null` value (meaning failure to match), or an associative array
 (the values matched).
 
-## The default route matcher
+## The default Route Matcher
 
 zend-console's default routing implementation is `Zend\Console\RouteMatcher\DefaultRouteMatcher`.
 Its constructor expects:
@@ -89,13 +89,13 @@ The arguments are as follows:
   validators are used to validate values, and provide more options than simply
   regular expressions (as used with the `$constraints`).
 
-> ### Single routes only
+> ### Single Routes only
 >
 > `DefaultRouteMatcher` instances define *a single console route to match*. Most
 > times, you will want to define multiple routes. The zend-mvc integration and
 > zf-console both provide methods for aggregating routes.
 
-## Routing strings
+## Routing Strings
 
 Routing strings consist of one or more of the following:
 
@@ -106,7 +106,7 @@ Routing strings consist of one or more of the following:
 - [Named literal alternative groups](#grouping-literal-alternatives) (e.g., `(all|some|none):filter`)
 - [Catch-all parameters](#catch-all-parameters) (e.g. `[...params]`)
 
-### Literal parameters
+### Literal Parameters
 
 *Literal parameters* are expected to appear on the command line exactly the way
 they are provided in the route. For example:
@@ -168,7 +168,7 @@ $ zf show admin users
 >
 > As such, you can use whitespace for readability.
 
-### Literal flags
+### Literal Flags
 
 Console tools commonly use flags. zend-console allows you to define any number
 of optional and/or mandatory flags.
@@ -224,7 +224,7 @@ $ zf check users -t -f -v
 # etc.
 ```
 
-### Positional value parameters
+### Positional Value Parameters
 
 Value parameters capture any text-based input, and come in two forms: positional
 and flags (which we've already discussed).
@@ -282,7 +282,7 @@ This allows us to capture commands such as the following:
 $ zf create user Johnny Bravo john@acme.org Entertainer
 ```
 
-> #### Escaping
+> ### Escaping
 >
 > Command line arguments on all systems must be properly escaped; otherwise they
 > will not be passed to our application correctly. For example, to create a user
@@ -293,7 +293,7 @@ $ zf create user Johnny Bravo john@acme.org Entertainer
 > $ zf create user "Johnan Tom" Bravo john@acme.org "Head of the Entertainment Department"
 > ```
 
-### Value flag parameters
+### Value Flag Parameters
 
 Positional value parameters are only matched if they appear in the exact order described in the
 route. If we do not want to enforce the order of parameters, we can define **value flags**.
@@ -320,7 +320,7 @@ $ zf find user --position "Head of the Entertainment Department"
 
 As noted, the order of flags is irrelevant for the parser.
 
-> ##### Providing values
+> ### Providing Values
 >
 > The parser understands values that are provided after either an equals symbol
 > (`=`) or a single space, but only if the value itself does not contain
@@ -345,7 +345,7 @@ $ zf rename user --id=123 --lastName=Bravo
 # etc.
 ```
 
-### Grouping literal alternatives
+### Grouping Literal Alternatives
 
 In the flags section, we demonstrated grouping alternative flags:
 
@@ -419,7 +419,7 @@ If the user entered the command line `say loudly I am here`, the 'volume'
 parameter would contain `'loudly'` and the 'words' parameter would contain
 `['I', 'am', 'here']`.
 
-## Console routes cheat-sheet
+## Console Routes Cheat-Sheet
 
 Param type                        | Example route definition    | Explanation
 :---                              | :---                        | :---
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,6 +1,6 @@
 docs_dir: docs/book
 site_dir: docs/html
-pages:
+nav:
     - Home: index.md
     - Introduction: intro.md
     - Reference:
@@ -17,6 +17,7 @@ pages:
         - 'Fetching Options and Arguments': getopt/fetching.md
         - Configuration: getopt/configuration.md
 site_name: zend-console
-site_description: Zend\Console
+site_description: 'Build console applications using getopt syntax or routing, complete with prompts'
 repo_url: 'https://github.com/zendframework/zend-console'
-copyright: 'Copyright (c) 2005-2019 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'
+extra:
+    show_special_homepage: true

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Console adapters`
	`1`	`+# Console Adapters`
`2`	`2`
`3`	`3`	`zend-console's console abstraction layer works around various bugs and limitations`
`4`	`4`	`in operating systems, including:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Configuring Zend\\Console\\Getopt`
	`1`	`+# Configuration`
`2`	`2`
`3`	`3`	`## Adding Option Rules`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Zend\\Console\\Getopt`
	`1`	`+# Introduction`
`2`	`2`
`3`	`3`	The `Zend\Console\Getopt` class helps command-line applications to parse their
`4`	`4`	`options and arguments.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Declaring Getopt Rules`
	`1`	`+# Declaring Rules`
`2`	`2`
`3`	`3`	The constructor for the `Zend\Console\Getopt` class takes from one to three
`4`	`4`	`arguments. The first argument declares which options are supported by your`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Console-aware modules`
	`1`	`+# Console-Aware Modules`
`2`	`2`
`3`	`3`	`zend-mvc integrates with zend-console; the integration also works with modules`
`4`	`4`	`loaded with the`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Console prompts`
	`1`	`+# Console Prompts`
`2`	`2`
`3`	`3`	`In addition to the console abstraction layer, zend-console provides numerous`
`4`	`4`	`convenience classes for interacting with the user in a console environment. This`