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,

components/symfony-bundle.rst

@@ -18,7 +18,7 @@ Security Issues
 ---------------
 
 If you discover any security related issues,
-please contact us at security@php-http.org instead of submitting an issue on GitHub.
+please contact us at tobias.nyholm@gmail.com instead of submitting an issue on GitHub.
 This allows us to fix the issue and release a security hotfix without publicly disclosing the vulnerability.
 
 

components/translator.rst

@@ -2,14 +2,18 @@ Adding extractors
 =================
 
 The extractor library is very SOLID which means that you easily can add extractors
-without changing existing code. There are some concepts to be aware of:
+without changing existing code. There are some concepts to be aware of
 
-The ``Extrator`` object has a collection of **FileExtractor** that are executed
+The ``Extractor`` object has a collection of ``FileExtractor`` that are executed
 on files with a file type they support. The ``PHPFileExtractor`` and ``TwigFileExtractor``
-are using the `visitor pattern`_.
-They have a collection of ``Translation\Extractor\Visitor`` that will be executed
-for each file the FileExtractor is running for. To add a custom extractor for a
-custom PHP class you may only add a visitor for the ``PHPFileExtractor``.
+are using the `visitor pattern`_. They have a collection of ``Translation\Extractor\Visitor``
+that will be executed for each file the FileExtractor is running for. To add a
+custom extractor for a custom PHP class you may only add a visitor for the ``PHPFileExtractor``.
+
+.. note::
+
+    Read more about the architecture at the component description of
+    :doc:`../components/extractor`.
 
 Example
 -------

conf.py

@@ -9,6 +9,6 @@ When you are using the auto translation features you may want to cache the respo
 from your paid third party translator services. To configure HTTPlug to be aggressive
 for those request you need the CachePlugin and the UrlMathcher.
 
-TODO Show how to configure the CachePlugin to cache google translate calls.
+TODO Show how to configure the CachePlugin to cache Google translate calls.
 
 .. _introduction: http://docs.php-http.org/en/latest/httplug/users.html

development/contributing.rst

@@ -0,0 +1,4 @@
+How to use Loco Adapter
+=======================
+
+This is an example of how to use an platform adapter with the Symfony bundle.