Updating the documentation.

wepay · Oct 28, 2015 · f3edd9d · f3edd9d
1 parent a0e6130
commit f3edd9d
Show file tree

Hide file tree

Showing 6 changed files with 89 additions and 174 deletions.
diff --git a/Makefile b/Makefile
@@ -16,7 +16,7 @@ test:
 
 .PHONY: docs
 docs:
-	php bin/sami.php update docs/sami-config.php
+	php bin/sami.php update docs/sami-config.php -v
 
 .PHONY: pushdocs
 pushdocs: docs

diff --git a/README.md b/README.md
@@ -27,186 +27,16 @@ This project uses [Semantic Versioning](http://semver.org) for managing backward
 
 ## Examples
 
-```php
-use WePay\Signer\Signer;
-
-$client_id = 'k3qDQy0Tr56v1ceo';
-$client_secret = 'O5j@pG@Jt%AzyiJTEfo!£LSz8yqSj)JX)S6FvW%58KjlS9bc%Fi7&&C4KSCT8hxd';
-
-$signer = new Signer($client_id, $client_secret);
-$signature = $signer->sign([
-    'ClientID' => $client_id,
-    'Domain'   => 'foo.com',
-    'Path'     => '/',
-    'Expires'  => 'Wed, 13 Jan 2021 22:23:01 GMT',
-    'Secure'   => null,
-    'HttpOnly' => null,
-]);
-
-$signature = wordwrap($signature, 64, "\n", true);
-#=> dfbffab5b6f7156402da8147886bba3eba67bd5baf2e780ba9d39e8437db7c47
-#=> 35e9a0b834aa21ac76f98da8c52a2a0cd1b0192d0f0df5c98e3848b1b2e1a037
-```
-
-
 ## Installation
 
-Using [Composer]:
-```bash
-composer require wepay/signer=^1.0.0
-```
-
-And include it in your scripts:
-
-```php
-require_once 'vendor/autoload.php';
-```
-
-
 ## Testing
 
-Firstly, run `make install` to download and install the dependencies.
-
-You can run the tests as follows:
-```bash
-make test
-```
-
-
 ## Debug Logging
 
-> **NOTE:** You should _only_ use logging during development — never in production.
-
-Signer implements the [PSR-3](https://github.com/php-fig/log) `Psr\Log\LoggerAwareInterface`. Because of this,
-you can inject any PSR-3-compatible logging package, and Signer will use it to log `DEBUG`-level messages.
-
-```php
-use Monolog\Logger;
-use Monolog\Handler\StreamHandler;
-use WePay\Signer\Signer;
-
-// create a log channel
-$log = new Logger('name');
-$log->pushHandler(new StreamHandler('path/to/your.log', Logger::DEBUG));
-
-// inject a logger
-$signer = new Signer();
-$signer->setLogger($log);
-
-$signer->sign( ... );
-```
-
-
-## Testing
-
-Firstly, run `make install` to download and install the dependencies.
-
-You can run the tests as follows:
-
-```bash
-make test
-```
-
-
-## API Reference
-
-The API Reference is generated by a tool called [Sami](https://github.com/FriendsOfPHP/Sami). Once it's installed, you 
-can generate updated documentation by running the following command in the root of the repository.
-
-```bash
-make docs
-```
-
-
 ## Deploying
 
-1. The `Makefile` (yes, `Makefile`) has a series of commands to simplify the development and deployment process.
-1. Also install [Chag](https://github.com/mtdowling/chag). This is used for managing the CHANGELOG and annotating the Git release correctly.
-
-### Updating the CHANGELOG
-
-Make sure that the [[CHANGELOG.md]] is human-friendly. See <http://keepachangelog.com> if you don’t know how.
-
-### `make`
-
-Running `make` by itself will show you a list of available sub-commands.
-
-```bash
-$ make
-all
-docs
-install
-pushdocs
-tag
-test
-version
-```
-
-### `make pushdocs`
-You will need to have write-access to the `wepay/signer-php` repository on GitHub. You should have already set up:
-
-* Your SSH key with your GitHub account.
-* Had your GitHub user given write-access to the repository.
-
-Then you can run:
-
-```bash
-make pushdocs
-```
-
-You can view your changes at <https://wepay.github.io/signer-php/>.
-
-### `make version`
-This allows you to set the version number for the next release.
-
-### `make tag`
-You will need to have a [Keybase](https://keybase.io) account first, including setting-up the
-[`keybase` CLI tool](https://keybase.io/docs/command_line/prerequisites).
-
-Then you can run:
-
-```bash
-make tag
-```
-
-You can view your changes in the `SIGNED.md` file.
-
-### Drafting a GitHub release
-
-1. Go to https://github.com/wepay/signer-php/tags
-1. Find the new tag that you just pushed. Click the ellipsis (`…`) to see the commit notes. Copy these.
-1. To the right, choose _Add release notes_. Your _Tag version_ should be pre-filled.
-1. The _Release title_ should match your _Tag version_.
-1. Inside _Describe this release_, paste the notes that you copied on the previous page.
-1. Choose _Publish release_.
-1. Your release should now be the latest. https://github.com/wepay/signer-php/releases/latest
-
-
 ## Contributing
-Here's the process for contributing:
-
-1. Fork Signer-PHP to your GitHub account.
-2. Clone your GitHub copy of the repository into your local workspace.
-3. Write code, fix bugs, and add tests with 100% code coverage.
-4. Commit your changes to your local workspace and push them up to your GitHub copy.
-5. You submit a GitHub pull request with a description of what the change is.
-6. The contribution is reviewed. Maybe there will be some banter back-and-forth in the comments.
-7. If all goes well, your pull request will be accepted and your changes are merged in.
-
 
 ## Authors, Copyright & Licensing
 
-* Copyright (c) 2015 [WePay](http://wepay.com)
-
-See also the list of [contributors](https://github.com/wepay/signer-ruby/graphs/contributors) who participated in this project.
-
-Licensed for use under the terms of the [Apache 2.0] license.
-
-  [Apache 2.0]: http://opensource.org/licenses/Apache-2.0
-
-
 ## Coding Standards
-
-PSR-0/1/2 are a solid foundation, but are not an entire coding style by themselves. I have taken the time to document all of the nitpicky patterns and nuances of my personal coding style. It goes well-beyond brace placement and tabs vs. spaces to cover topics such as docblock annotations, ternary operations and which variation of English to use. It aims for thoroughness and pedanticism over hoping that we can all get along.
-
-<https://github.com/skyzyx/php-coding-standards>
diff --git a/docs/api-reference.rst b/docs/api-reference.rst
@@ -7,8 +7,8 @@ repository.
 
 .. code:: bash
 
-    bin/sami.php update docs/sami-config.php -v
+    make docs
 
 You can view the API reference at https://wepay.github.io/signer-php/.
 
-.. _Sami: http://phpdoc.org
+.. _Sami: https://github.com/FriendsOfPHP/Sami
diff --git a/docs/deploying.rst b/docs/deploying.rst
@@ -0,0 +1,84 @@
+Deploying
+=========
+
+1. The ``Makefile`` (yes, ``Makefile``) has a series of commands to
+   simplify the development and deployment process.
+2. Also install `Chag`_. This is used for managing the CHANGELOG and annotating
+   the Git release correctly.
+
+Updating the CHANGELOG
+----------------------
+
+Make sure that the ``CHANGELOG.md`` is human-friendly. See
+http://keepachangelog.com if you don’t know how.
+
+``make``
+--------
+
+Running ``make`` by itself will show you a list of available sub-commands.
+
+.. code:: bash
+
+    $ make
+    all
+    docs
+    install
+    pushdocs
+    tag
+    test
+    version
+
+``make pushdocs``
+-----------------
+
+You will need to have write-access to the ``wepay/signer-php`` repository on
+GitHub. You should have already set up:
+
+-  Your SSH key with your GitHub account.
+-  Had your GitHub user given write-access to the repository.
+
+Then you can run:
+
+.. code:: bash
+
+    make pushdocs
+
+You can view your changes at https://wepay.github.io/signer-php/.
+
+``make version``
+----------------
+
+This allows you to set the version number for the next release.
+
+``make tag``
+------------
+
+You will need to have a `Keybase`_ account first, including setting-up the
+```keybase`` CLI tool`_.
+
+Then you can run:
+
+.. code:: bash
+
+    make tag
+
+You can view your changes in the ``SIGNED.md`` file.
+
+Drafting a GitHub release
+-------------------------
+
+1. Go to https://github.com/wepay/signer-php/tags
+2. Find the new tag that you just pushed. Click the ellipsis (``…``) to
+   see the commit notes. Copy these.
+3. To the right, choose *Add release notes*. Your *Tag version* should
+   be pre-filled.
+4. The *Release title* should match your *Tag version*.
+5. Inside *Describe this release*, paste the notes that you copied on
+   the previous page.
+6. Choose *Publish release*.
+7. Your release should now be the latest.
+   https://github.com/wepay/signer-php/releases/latest
+
+.. _Chag: https://github.com/mtdowling/chag
+.. _Keybase: https://keybase.io
+.. _``keybase`` CLI tool: https://keybase.io/docs/command_line/prerequisites
diff --git a/docs/index.rst b/docs/index.rst
@@ -37,6 +37,7 @@ User guide
    contributing
    copyright
    coding-standards
+   deploying
 
 
 .. |Source| image:: http://img.shields.io/badge/source-wepay/signer–php-blue.svg?style=flat-square

diff --git a/docs/testing.rst b/docs/testing.rst
@@ -8,6 +8,6 @@ You can run the tests as follows:
 
 .. code:: bash
 
-    bin/phpunit
+    make test
 
 You can check on the current test status at https://travis-ci.org/wepay/signer-php.