Merge pull request #308 from moneyphp/doc

Refactor documentation structure

doc/_static/custom.css

@@ -1,3 +1,16 @@
 .row-even .line-block, .row-odd .line-block {
     margin-left: 0;
 }
+
+.versionmodified {
+    font-weight: bold;
+}
+
+.wy-menu-vertical p.caption {
+    color: #b3b3b3;
+    margin-top: 16px;
+    margin-bottom: 0;
+}
+.wy-menu-vertical p.caption .caption-text {
+    font-size: 120%;
+}

doc/concept.rst

@@ -0,0 +1,87 @@
+Concept
+=======
+
+This section introduces the concept and basic features of the library
+
+Immutability
+------------
+
+Jim and Hannah both want to buy a copy of book priced at EUR 25.
+
+.. code-block:: php
+
+    use Money\Money;
+
+    $jimPrice = $hannahPrice = Money::EUR(2500);
+
+
+Jim has a coupon for EUR 5.
+
+.. code-block:: php
+
+    $coupon = Money::EUR(500);
+    $jimPrice->subtract($coupon);
+
+
+Because ``$jimPrice`` and ``$hannahPrice`` are the same object, you'd expect Hannah to now have the reduced
+price as well. To prevent this problem, Money objects are **immutable**. With the code above, both
+``$jimPrice`` and ``$hannahPrice`` are still EUR 25:
+
+.. code-block:: php
+
+   $jimPrice->equals($hannahPrice); // true
+
+
+The correct way of doing operations is:
+
+.. code-block:: php
+
+   $jimPrice = $jimPrice->subtract($coupon);
+   $jimPrice->lessThan($hannahPrice); // true
+   $jimPrice->equals(Money::EUR(2000)); // true
+
+
+Integer Limit
+-------------
+
+Although in real life it is highly unprobable, you might have to deal with money values greater than
+the integer limit of your system (``PHP_INT_MAX`` constant represents the maximum integer value).
+
+In order to bypass this limit, we introduced `Calculators`. Based on your environment, Money automatically
+picks the best internally and globally. The following implementations are available:
+
+- BC Math (requires `bcmath` extension)
+- GMP (requires `gmp` extension)
+- Plain integer
+
+Calculators are checked for availability in the order above. If no suitable Calculator is found
+Money silently falls back to the integer implementation.
+
+Because of PHP's integer limit, money values are stored as string internally and
+``Money::getAmount`` also returns string.
+
+.. code-block:: php
+
+    use Money\Currency;
+    use Money\Money;
+
+    $hugeAmount = new Money('12345678901234567890', new Currency('USD'));
+
+
+.. note::
+    Remember, because of the integer limit in PHP, you should inject a string that represents your huge amount.
+
+
+JSON
+----
+
+If you want to serialize a money object into a JSON, you can just use the PHP method ``json_encode`` for that.
+Please find below example of how to achieve this.
+
+.. code-block:: php
+
+    use Money\Money;
+
+    $money = Money::USD(350);
+    $json = json_encode($money);
+    echo $json; // outputs '{"amount":"350","currency":"USD"}'

doc/conf.py

@@ -60,7 +60,7 @@
 
 # General information about the project.
 project = u'Money'
-copyright = u'2011-2016, Mathias Verraes'
+copyright = u'2011-2016, Mathias Verraes, 2016 The Money PHP Team'
 author = u'The Money PHP Team'
 
 # The version info for the project you're documenting, acts as replacement for

doc/Bitcoin.rst → doc/features/bitcoin.rst

@@ -1,3 +1,5 @@
+.. _bitcoin:
+
 Bitcoin
 =======
 
@@ -32,4 +34,4 @@ Please see the example below how to use the Bitcoin currency:
 
 In most cases you probably don't know the exact currency you are going to format or parse.
 For such scenarios, we have an aggregate formatter and a parser which lets you configure multiple parsers
-and then choose the best based on the value. See more in :doc:`Formatting` and :doc:`Parsing` section.
+and then choose the best based on the value. See more in :ref:`Formatting <formatting>` and :ref:`Parsing <parsing>` section.

doc/Formatting.rst → doc/features/formatting.rst

@@ -1,3 +1,5 @@
+.. _formatting:
+
 Formatting
 ==========
 
@@ -93,4 +95,4 @@ and want to support multiple currencies.
 Bitcoin Formatter
 -----------------
 
-See :doc:`Bitcoin`.
+See :ref:`Bitcoin <bitcoin>`.

doc/Parsing.rst → doc/features/parsing.rst

@@ -1,3 +1,5 @@
+.. _parsing:
+
 Parsing
 =======
 
@@ -87,4 +89,4 @@ This is very useful if you want to use one parser as a service in DI context.
 Bitcoin Parser
 --------------
 
-See :doc:`Bitcoin`.
+See :ref:`Bitcoin <bitcoin>`.

doc/index.rst

@@ -1,18 +1,54 @@
 Money for PHP
 =============
 
+This library intends to provide tools for storing and using monetary values in an easy, yet powerful way.
+
+
+Why a Money library for PHP?
+----------------------------
+
+Also see http://blog.verraes.net/2011/04/fowler-money-pattern-in-php/
+
+This is a PHP implementation of the Money pattern, as described in [Fowler2002]_ :
+
+   A large proportion of the computers in this world manipulate money, so it's always puzzled me
+   that money isn't actually a first class data type in any mainstream programming language. The
+   lack of a type causes problems, the most obvious surrounding currencies. If all your calculations
+   are done in a single currency, this isn't a huge problem, but once you involve multiple currencies
+   you want to avoid adding your dollars to your yen without taking the currency differences into
+   account. The more subtle problem is with rounding. Monetary calculations are often rounded to the
+   smallest currency unit. When you do this it's easy to lose pennies (or your local equivalent)
+   because of rounding errors.
+
+.. [Fowler2002] Fowler, M., D. Rice, M. Foemmel, E. Hieatt, R. Mee, and R. Stafford, Patterns of Enterprise Application Architecture, Addison-Wesley, 2002. http://martinfowler.com/books.html#eaa
+
+
+The goal
+--------
+
+Implement a reusable Money class in PHP, using all the best practices and taking care of all the
+subtle intricacies of handling money.
+
+.. toctree::
+   :hidden:
+
+   Money <self>
+   getting-started
+   concept
+   inspiration
+
 .. toctree::
-   :maxdepth: 2
-
-   Introduction
-   GettingStarted
-   Immutability
-   Allocation
-   Currencies
-   CurrencyConversion
-   Json
-   IntegerLimit
-   Formatting
-   Parsing
-   Bitcoin
-   Inspiration
+   :hidden:
+   :caption: Features
+   :maxdepth: 3
+
+   features/allocation
+   features/bitcoin
+   features/currencies
+   features/currency-conversion
+   features/formatting
+   features/parsing
+
+.. |clearfloat|  raw:: html
+
+    <div style="clear:left"></div>