Merge branch 'feature/documentation' into develop

Close #10
Fixes #8
Fixes #7
Fixes #6
Fixes #5
Fixes #4

.gitignore

@@ -6,7 +6,9 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock

.travis.yml

@@ -10,22 +10,43 @@ branches:
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
+
+env:
+  global:
+    - SITE_URL: https://zendframework.github.io/zend-text
+    - GH_USER_NAME: "Matthew Weier O'Phinney"
+    - GH_USER_EMAIL: [email protected]
+    - GH_REF: github.com/zendframework/zend-text.git
+    - secure: "PByCrJOLcuybgT2Kk3bb5gPrv1sD2MiOa/3ZBs0EN1TF7mhtc7w6EaatD1TCKEWT8VhbsCvZNZzl7/PdetxXS09Ld8s2vshM6KbGSjn+TTmiNOq/GuvBGBTD9VVeAG0MKn0sq/Aq0NMM5Onelu0kAmOFb5yj3P5lXSc4MzWOBYBkbCBNjd7RYFZ+5YzSb9BdGPP2P2OvoTxBmmfZuZ5l0U9agarLejURVzlppLriL35dVdmo/CA2Ki4lOVEUVCuO4iR7qEz7TokWrku9y+p7hk5TfHeC3FF8jeyXiklCKT2kT0wbWcE5IV/kkzPBUdcVdpXL0hA8BKekLiNhpRnqDKBaBtQmp5VocgPEWlxtOweb0rs5KfPjxPpjNQ6FGg2DiA95nswrLAJIPYZyG+RKaL98kfzAC62V81x2OK1PEI5FXOqZxNjrJKPw345VHi8aMCnGDtbA3YN6Jke1Syy0hpQ5gs4x8CqaiJVCKI70rbjZE+ZXBIo/PO6VyI8km2cpG69jCUKO9Jt/q5ZbbIPAXPElpS2BezGs8Qqz99JGBAfizRf1tF2jZQw6L6YAaewXSYRA+37i57fYxd+1QyBuI5JMjqqxBahKOzoa1Xz5uWNYJeU5aV/sw1xtyjTZx7wYcClVsgXH58V+T1Umh4qvD5NE1n5P8L/4013MBnehXtc="
 
 matrix:
   fast_finish: true
   include:
     - php: 5.5
       env:
-        - SERVICE_MANAGER_VERSION="^2.7.5"
         - EXECUTE_CS_CHECK=true
-    - php: 5.6
+    - php: 5.5
       env:
         - SERVICE_MANAGER_VERSION="^2.7.5"
+    - php: 5.6
+      env:
         - EXECUTE_TEST_COVERALLS=true
+        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
+        - PATH="$HOME/.local/bin:$PATH"
+    - php: 5.6
+      env:
+        - SERVICE_MANAGER_VERSION="^2.7.5"
     - php: 7
+    - php: 7
+      env:
+        - SERVICE_MANAGER_VERSION="^2.7.5"
     - php: hhvm 
+    - php: hhvm
+      env:
+        - SERVICE_MANAGER_VERSION="^2.7.5"
   allow_failures:
-    - php: 7
     - php: hhvm
 
 notifications:
@@ -46,6 +67,10 @@ script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
   - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
   - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
+  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
+
+after_success:
+  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi

CHANGELOG.md

@@ -6,7 +6,8 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Added
 
-- Nothing.
+- [#10](https://github.com/zendframework/zend-text/pull/10) adds and publishes
+  documentation; view it at https://zendframework.github.io/zend-text/
 
 ### Deprecated
 

README.md

@@ -17,4 +17,4 @@
 
 
 - File issues at https://github.com/zendframework/zend-text/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-text
+- Documentation is at https://zendframework.github.io/zend-text/

doc/book/figlet.md

@@ -0,0 +1,72 @@
+# Figlets
+
+`Zend\Text\Figlet` is a component which enables developers to create a so called FIGlet text.
+FIGlet text is a string represented as *ASCII* art.
+
+FIGlets use a special font format, called FLT (FigLet Font). By default, one
+standard font is shipped with `Zend\Text\Figlet`, but you can download
+additional fonts at [http://www.figlet.org](http://www.figlet.org).
+
+> ## Compressed fonts
+>
+> `Zend\Text\Figlet` supports gzipped fonts. This means that you can take an
+> `.flf` file and gzip it.  To allow `Zend\Text\Figlet` to recognize this, the
+> gzipped font must have the extension `.gz`.  Further, to be able to use
+> gzipped fonts, you have to have enabled the PHP GZIP extension.
+
+> ## Encoding
+>
+> `Zend\Text\Figlet` expects your strings to be UTF-8 encoded by default. If
+> this is not the case, you can supply the character encoding to the second
+> parameter to the `render()` method.
+
+You can define multiple options for a FIGlet. When instantiating
+`Zend\Text\Figlet\Figlet`, you can supply an array, a `Traversable` that
+supplies both keys and values, or an instance of `Zend\Config\Config`.
+
+- `font`: Defines the font which should be used for rendering. If not defines,
+  the built-in font will be used.
+- `outputWidth`: Defines the maximum width of the output string. This is used
+  for word-wrap as well as justification. Be careful when using small values;
+  they may result in an undefined behaviour. The default value is 80.
+- `handleParagraphs`: A boolean which indicates how new lines are handled. When
+  set to `TRUE`, single new lines are ignored and instead treated as single
+  spaces; only multiple new lines will be handled as such. The default value is
+  `FALSE`.
+- `justification`: May be one of the `Zend\Text\Figlet\Figlet::JUSTIFICATION_*`
+  constants, which include `JUSTIFICATION_LEFT`, `JUSTIFICATION_CENTER`, and
+  `JUSTIFICATION_RIGHT` The default justification is defined by the
+  `rightToLeft` value.
+- `rightToLeft`: Defines the direction in which text is written. May be either
+  `Zend\Text\Figlet\Figlet::DIRECTION_LEFT_TO_RIGHT` or
+  `Zend\Text\Figlet\Figlet::DIRECTION_RIGHT_TO_LEFT`. By default, the setting of
+  the font file is used.  When justification is not defined, a text written from
+  right-to-left is automatically right-aligned.
+- `smushMode`: An integer bitfield which defines how single characters are
+  smushed together; can be the sum of multiple values from
+  `Zend\Text\Figlet\Figlet::SM_*`. The component defines the following smush
+  modes: `SM_EQUAL`, `SM_LOWLINE`, `SM_HIERARCHY`, `SM_PAIR`, `SM_BIGX`,
+  `SM_HARDBLANK`, `SM_KERN`, and `SM_SMUSH`. A value of 0 doesn't disable the
+  entire smushing, but forces `SM_KERN` to be applied, while a value of -1
+  disables it. An explanation of the different smush modes can be found
+  [here](http://www.jave.de/figlet/figfont.txt). By default the setting of the
+  font file is used. The smush mode option is normally used only by font
+  designers testing the various layoutmodes with a new font.
+
+## Basic Usage
+
+```php
+$figlet = new Zend\Text\Figlet\Figlet();
+echo $figlet->render('Zend');
+```
+
+Assuming you are using a monospace font, the above results in the following:
+
+```
+  ______    ______    _  __   ______
+ |__  //   |  ___||  | \| || |  __ \\
+   / //    | ||__    |  ' || | |  \ ||
+  / //__   | ||___   | .  || | |__/ ||
+ /_____||  |_____||  |_|\_|| |_____//
+ `-----`'  `-----`   `-` -`'  -----`
+```

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-text</h1>
+
+    <p>Create FIGlets and text-based tables.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-text</code></pre>
+  </div>
+</div>
+

doc/book/index.md

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

doc/book/table.md

@@ -0,0 +1,107 @@
+# Tables
+
+`Zend\Text\Table` is a component for creating text-based tables on the fly using
+decorators.  This can be helpful for sending structured data in text emails, or
+to display table information in a CLI application. `Zend\Text\Table` supports
+multi-line columns, column spans, and alignment.
+
+> ## Encoding
+>
+> `Zend\Text\Table` expects your strings to be UTF-8 encoded by default. If this
+> is not the case, you can either supply the character encoding as a parameter
+> to the constructor or the `setContent()` method of `Zend\Text\Table\Column`.
+> Alternately, if you have a different encoding in the entire process, you can
+> define the standard input charset with
+> `Zend\Text\Table\Table::setInputCharset($charset)`. In case you need another
+> output charset for the table, you can set it with
+> `Zend\Text\Table\Table::setOutputCharset($charset)`.
+
+A `Zend\Text\Table\Table` object consists of rows which contain columns,
+represented by `Zend\Text\Table\Row` and `Zend\Text\Table\Column`, respectively.
+When creating a table, you can supply an array with options for the table.
+
+Options include:
+
+- `columnWidths` (required): An array defining all columns width their widths in characters.
+- `decorator`: The decorator to use for the table borders. The default is
+  `unicode`, but you may also specify `ascii` or give an instance of a custom
+  decorator object.
+- `padding`: The number of characters of left and right padding within the
+  columns. The default padding is zero.
+- `AutoSeparate`: How the rows are separated with horizontal lines; the default
+  is to separate all rows. This is defined as a bitmask containing one ore more
+  of the following `Zend\Text\Table` constants:
+  - `Zend\Text\Table\Table::AUTO_SEPARATE_NONE`
+  - `Zend\Text\Table\Table::AUTO_SEPARATE_HEADER`
+  - `Zend\Text\Table\Table::AUTO_SEPARATE_FOOTER`
+  - `Zend\Text\Table\Table::AUTO_SEPARATE_ALL`
+  Where header is always the first row, and the footer is always the last row.
+
+Rows are added to the table by creating a new instance of `Zend\Text\Table\Row`
+and appending it to the table via the `appendRow()` method. Rows themselves have
+no options. You can also provide the `appendRow()` method with an array of
+options describing a row; these will then be automatically converted to a row
+object, containing multiple column objects.
+
+Adding columns follows the same process as adding rows.  Create a new instance
+of `Zend\Text\Table\Column` and then either set the column options in the
+constructor or later with the `set*()` methods. The first parameter is the
+content of the column; content may have multiple lines, which should be
+separated by `\n` characters. The second parameter defines the alignment, which
+is 'left' by default, but can be any of the following `Zend\Text\Table\Column`
+constant values:
+
+- `ALIGN_LEFT`
+- `ALIGN_CENTER`
+- `ALIGN_RIGHT`
+
+The third parameter is the column span. For example, when you provide the value "2", the
+column will span two columns of the table.
+
+The last parameter defines the encoding of the content, which should be
+supplied only if the content is neither ASCII nor UTF-8.
+
+To append the column to the row, call `appendColumn()` in your row object with
+the column object as a parameter. Alternately, provide a string to the
+`appendColumn()` method.
+
+To render the table, use the `render()` method, or rely on the
+`__toString()` implementation to do implicit casting
+
+```php
+echo $table;
+
+// or
+$tableString = (string) $table`;
+```
+
+## Basic Usage
+
+```php
+$table = new Zend\Text\Table\Table([
+    'columnWidths' => [10, 20]
+]);
+
+// Implicitly build rows, by supply an array of column values:
+$table->appendRow(['Zend', 'Framework']);
+
+// Or build the row and column manually:
+$row = new Zend\Text\Table\Row();
+
+$row->appendColumn(new Zend\Text\Table\Column('Zend'));
+$row->appendColumn(new Zend\Text\Table\Column('Framework'));
+
+$table->appendRow($row);
+
+echo $table;
+```
+
+The above results in the following output:
+
+```php
+┌──────────┬────────────────────┐
+│Zend      │Framework           │
+|──────────|────────────────────|
+│Zend      │Framework           │
+└──────────┴────────────────────┘
+```