Reorganize the documentation and add plenty of info (#6)

* Moved platform adapters to the bottom of the list

* Moved around order in the docs. This sets a good structure

* Added docs about common and extractor

* typos

* Added docs about translation component

* typos

* typos

* minor

* Added info about platform adapter component

* Updated toctree

* Added docs for Symfony

* Added more docs about Symfony

* typos

* Added better toc

* Minor fixes

* Remove primary domain

* added favicon

Author: Nyholm

CONTRIBUTING

@@ -1 +1 @@
-Please see http://docs.php-http.org/en/latest/development/contributing.html
+Please see http://php-translation.readthedocs.io/en/latest/development/contributing.html

_static/custom.css

@@ -10,6 +10,7 @@
     color: #b3b3b3;
     margin-top: 16px;
     margin-bottom: 0;
+    margin-left: 1.4em
 }
 .wy-menu-vertical p.caption .caption-text {
     font-size: 120%;

assets/image/webui-dashboard.png

@@ -0,0 +1,29 @@
+Common
+======
+
+The Common component is the least exiting component. It contains common interfaces
+and classes that are used by many other packages in this organization. The most
+important ones are listed on this page.
+
+Message
+-------
+
+The ``Message`` class is a representation of a translation in a specific language. This
+class is commonly used as a parameter or a return value for functions in the organisation.
+
+The message contains of an ``key``, ``domain``, ``locale`` and ``translation``.
+There is also an array where meta data can be stored. Example of usage of meta data
+could be when a third party translation service has flagged the translation as "fuzzy".
+
+Storage
+-------
+
+The ``Storage`` interface is an abstraction for places where you can store translations.
+There are many examples like on file system, in database or in any third party translation
+service. A ``Storage`` is very simple. It has methods for getting, updating and
+deleting a translation.
+
+Exception
+---------
+
+The ``Exception`` interface will decorate all the runtime exceptions in the organisation.

assets/image/webui-page.png

@@ -0,0 +1,86 @@
+Extractor
+=========
+
+The responsibility of the Extractor component is to get translation keys from the
+source code.
+
+Installation and Usage
+----------------------
+
+Install the extractor component with Composer
+
+.. code-block:: bash
+
+    composer require php-translation/extractor
+
+When the extractor is downloaded you may use it by doing the following:
+
+.. code-block:: php
+
+    require "vendor/autoload.php";
+
+    use Translation\Extractor\Visitor\Php\Symfony as Visitor;
+
+    // Create extractor for PHP files
+    $fileExtractor = new PHPFileExtractor()
+
+    // Add visitors
+    $fileExtractor->addVisitor(new Visitor\ContainerAwareTrans());
+    $fileExtractor->addVisitor(new Visitor\ContainerAwareTransChoice());
+    $fileExtractor->addVisitor(new Visitor\FlashMessage());
+    $fileExtractor->addVisitor(new Visitor\FormTypeChoices());
+
+    // Add the file extractor to Extractor
+    $extractor = new Extractor();
+    $extractor->addFileExtractor($this->getPHPFileExtractor());
+
+    //Start extracting files
+    $sourceCollection = $extractor->extractFromDirectory('/foo/bar');
+
+    // Print the result
+    foreach ($sourceCollection as $source) {
+      echo sprintf('Key "%s" found in %s at line %d', $source-getMessage(), $source->getPath(), $source->getLine());
+    }
+
+Architecture
+------------
+
+There is a lot of things happening the the code example above. Everything is very
+SOLID so it is easy to add your own extractors if you have custom features that
+you need to translate.
+
+The class that we interact with after when we want to extract translations is the
+``Extractor`` class. It supports ``Extractor::extractFromDirectory(string)`` and
+the more flexible ``Extractor::extract(Finder)``. The Extractor looks at all files
+in the directory and checks the type/extension. The extractor then executes all
+``FileExtractor`` for this file type.
+
+There is a few ``FileExtractor`` that comes with this component. They are ``PHPFileExtractor``,
+``TwigFileExtractor`` and ``BladeExtractor``. As you may guess they extract translations
+from PHP files, Twig files and Blade files respectively. The most interesting ones
+are ``PHPFileExtractor`` and ``TwigFileExtractor`` because they are using the `Visitor pattern`_
+to parse all the nodes in the document.
+
+Let's focus on the ``PHPFileExtractor`` only for a moment. We are using the Nikic
+PHP Parser to split the PHP source into an abstract syntax tree which enables us
+to statically analyze the source. Read more about this in the `nikic/php-parser`_
+documentation. When you add a visitor to the ``PHPFileExtractor`` it will be called
+for each node in the syntax tree.
+
+The visitors is very specific with what they are looking for. The ``FlashMessage``
+visitor is searching for a pattern like ``$this->addFlash()``. If that string is
+found it will add a new ``SourceLocation`` to the ``SourceCollection`` model.
+
+When all visitors and ``FileExtractor`` has been executed an instance of the ``SourceCollection``
+will be returned.
+
+.. note::
+
+    If you want to add functionality to the extractor you are most likely to add
+    a new visitor. See :doc:`../guides/adding-extractor` for more information.
+
+
+
+.. _`Visitor pattern`: https://en.wikipedia.org/wiki/Visitor_pattern
+.. _`nikic/php-parser`: https://github.com/nikic/PHP-Parser
+

components/common.rst

@@ -0,0 +1,48 @@
+Platform Adapters
+=================
+
+To be able to integrate with all the third party translation platforms we need adapters
+for each of them. The adapter converts the ``ThirdPartyPlatformApiClient`` into
+a ``Translation\Common\Storage``.
+
+The `platform adapter repository`_ is a "monolithic" repository. It uses `www.subtreesplit.com`_
+to push changes from ``php-translation/platform-adapter`` to ``php-translation/foo-adapter``.
+This setup will make it easier to maintain the adapters since it requires only one
+pull request to make a change on many adapters. Note that ``php-translation/foo-adapter``
+is a **read only** repository and changes should go to ``php-translation/platform-adapter``.
+
+The Adapters
+------------
+
+Each adapter has a a dependency on a API client. They also have different Composer
+requirements and may support different PHP version. All the adapters has a Symfony
+bundle for ease the integration with Symfony.
+
+To install an adapter in Symfony you need to download it with Composer, activate
+the bundle in ``AppKernel`` and then add some configuration. This procedure is described
+at each adapters repository.
+
+.. note::
+
+    See guide :doc:`../guides/using-loco-adapter`
+
+The table below shows the adapters and their platform where you can read more about
+the service.
+
+
+.. csv-table::
+   :header: "Platform", "Repository", "Badges"
+
+   "`Loco/Localise.biz <https://localise.biz/>`_", "`php-translation/loco-adapter <https://github.com/php-translation/loco-adapter/>`_", |vLoco| |dLoco|
+
+.. _`platform adapter repository`: https://github.com/php-translation/platform-adapter
+.. _`www.subtreesplit.com`: https://www.subtreesplit.com/
+
+.. Badges:
+
+.. |vLoco| image:: https://poser.pugx.org/php-translation/loco-adapter/v/stable
+   :target: https://packagist.org/packages/php-translation/loco-adapter
+.. |dLoco| image:: https://poser.pugx.org/php-translation/loco-adapter/downloads
+   :target: https://packagist.org/packages/php-translation/loco-adapter
+
+

components/extractor.rst

@@ -0,0 +1,39 @@
+Translator
+==========
+
+The Translator component provides an interface for translation services like Google
+Translate or Bing Translate.
+
+Installation and Usage
+----------------------
+
+Install the extractor component with Composer
+
+.. code-block:: bash
+
+    composer require php-translation/translator
+
+.. code-block:: php
+
+    require "vendor/autoload.php";
+
+    $translator = new Translator();
+    $translator->addTranslatorService(new GoogleTranslator('api_key'));
+
+    echo $translator->translate('apple', 'en', 'sv'); // "äpple"
+
+Architecture
+------------
+
+The ``Translator`` class could be considered a "chain translator" it asks the first
+translation service to translate the string. If the translation fails it asks the
+second service until a translation is found. If no translation is found a ``null``
+value will be returned.
+
+The ``Translator`` class is SOLID so you can easily add your custom translator into
+the chain.
+
+.. note::
+
+    Since most translator services are paid services you probably want to add aggressive
+    caching on the responses. See :doc:`../guides/configure-httplug` for more information.

components/platform-adapters.rst

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# PHP-HTTP documentation build configuration file, created by
+# PHP-Translation documentation build configuration file, created by
 # sphinx-quickstart on Sat Jan  2 15:26:57 2016.
 #
 # This file is execfile()d with the current directory set to its
@@ -21,7 +21,7 @@
 lexers['php'] = PhpLexer(startinline=True, linenos=1)
 lexers['php-annotations'] = PhpLexer(startinline=True)
 
-primary_domain = 'php'
+# primary_domain = 'php'
 highlight_language = 'php'
 
 # If extensions (or modules to document with autodoc) are in another directory,