Merge pull request #157 from martiis/doc_update

saimaz · saimaz · commit 2e085f01d9fa · 2015-01-27T15:55:02.000+02:00
Documentation update
diff --git a/README.rst b/README.rst
@@ -1,5 +1,5 @@
-Elasticsearch Bundle
-====================
+ONGR Elasticsearch Bundle
+=========================
 
 Elasticsearch Bundle was created in order to serve the need for
 professional `elasticsearch <http://www.elasticsearch.org>`_ integration with enterprise level Symfony
@@ -41,10 +41,12 @@ Technical goodies:
 Documentation
 -------------
 
-Documentation for ONGRElasticsearchBundle can be found in
-``Resources/doc/index.rst``
+The online documentation of the bundle is in `ongr.readthedocs.org <http://ongr.readthedocs.org/en/latest/components/ElasticsearchBundle/Resources/doc/index.html>`_
 
-`Read the documentation (master) <https://github.com/ongr-io/ElasticsearchBundle/blob/master/Resources/doc/index.rst>`_
+For contribution to the documentation you can find it on `Resources/doc <https://github.com/ongr-io/ElasticsearchBundle/tree/master/Resources/doc>`_.
+
+**Warning**: documentation files are not rendering correctly in Github (rst format)
+and some content might be broken or hidden, make sure to read raw files.
 
 License
 -------
diff --git a/Resources/doc/commands.rst b/Resources/doc/commands.rst
@@ -156,4 +156,93 @@ Type update
    | ``es:type:update --manager shop --type article --force``   | Updates mapping for ``shop`` *manager* type ``article``.      |
    +------------------------------------------------------------+---------------------------------------------------------------+
 
+Cache clear
+-----------
+
+- Command name: ``es:cache:clear``.
+- Description: Clears elasticsearch client cache.
+- Options:
+
+   +-----------------+---------------+------------------+-----------------------------------------------------------------------------------------------+
+   | Full name       | Short name    | Value            | What it does                                                                                  |
+   +=================+===============+==================+===============================================================================================+
+   | ``--manager``   | *undefined*   | Manager name.    | Used to select *manager* to update types for. If not specified, default manager is used.      |
+   +-----------------+---------------+------------------+-----------------------------------------------------------------------------------------------+
+
+-  Examples:
+
+   +------------------------------------------------------------+---------------------------------------------------------------+
+   | Input                                                      | What it does                                                  |
+   +============================================================+===============================================================+
+   | ``es:cache:clear``                                         | Clears client which *manager* is using cache.                 |
+   +------------------------------------------------------------+---------------------------------------------------------------+
+   | ``es:type:update --manager shop``                          | Clears client which ``shop`` *manager* is using cache.        |
+   +------------------------------------------------------------+---------------------------------------------------------------+
+
+Warmer put
+----------
+
+- Command name: ``es:warmer:put``.
+- Description: Puts warmers into elasticsearch.
+- Arguments:
+
+   +--------------+-----------------------------------------------------------------------------------------------------+
+   | Value        | What it specifies                                                                                   |
+   +==============+=====================================================================================================+
+   | Warmer name  | Array of tagged warmer names.                                                                       |
+   +--------------+-----------------------------------------------------------------------------------------------------+
+
+- Options:
+
+   +-----------------+---------------+------------------+-----------------------------------------------------------------------------------------------+
+   | Full name       | Short name    | Value            | What it does                                                                                  |
+   +=================+===============+==================+===============================================================================================+
+   | ``--manager``   | *undefined*   | Manager name.    | Used to select *manager* to update types for. If not specified, default manager is used.      |
+   +-----------------+---------------+------------------+-----------------------------------------------------------------------------------------------+
+
+-  Examples:
+
+   +------------------------------------------------------------+------------------------------------------------------------------------------------+
+   | Input                                                      | What it does                                                                       |
+   +============================================================+====================================================================================+
+   | ``es:warmer:put``                                          | Puts all warmers into client which *default* manager is using.                     |
+   +------------------------------------------------------------+------------------------------------------------------------------------------------+
+   | ``es:warmer:put --manager shop``                           | Puts all warmers into client which ``shop`` manager is using.                      |
+   +------------------------------------------------------------+------------------------------------------------------------------------------------+
+   | ``es:warmer:put foo baz --manager tuna``                   | Puts ``foo`` and ``baz`` named warmers into client which ``tuna`` manager is using |
+   +------------------------------------------------------------+------------------------------------------------------------------------------------+
+
+Warmer delete
+-------------
+
+- Command name: ``es:warmer:delete``.
+- Description: Removes warmers from elasticsearch.
+- Arguments:
+
+   +--------------+-----------------------------------------------------------------------------------------------------+
+   | Value        | What it specifies                                                                                   |
+   +==============+=====================================================================================================+
+   | Warmer name  | Array of tagged warmer names.                                                                       |
+   +--------------+-----------------------------------------------------------------------------------------------------+
+
+- Options:
+
+   +-----------------+---------------+------------------+-----------------------------------------------------------------------------------------------+
+   | Full name       | Short name    | Value            | What it does                                                                                  |
+   +=================+===============+==================+===============================================================================================+
+   | ``--manager``   | *undefined*   | Manager name.    | Used to select *manager* to update types for. If not specified, default manager is used.      |
+   +-----------------+---------------+------------------+-----------------------------------------------------------------------------------------------+
+
+-  Examples:
+
+   +------------------------------------------------------------+----------------------------------------------------------------------------------------+
+   | Input                                                      | What it does                                                                           |
+   +============================================================+========================================================================================+
+   | ``es:warmer:delete``                                       | Deletes all warmers from client which *default* manager is using.                      |
+   +------------------------------------------------------------+----------------------------------------------------------------------------------------+
+   | ``es:warmer:delete --manager shop``                        | Deletes all warmers from client which ``shop`` manager is using.                       |
+   +------------------------------------------------------------+----------------------------------------------------------------------------------------+
+   | ``es:warmer:delete foo baz --manager tuna``                | Deletes ``foo`` and ``baz`` named warmers from client which ``tuna`` manager is using. |
+   +------------------------------------------------------------+----------------------------------------------------------------------------------------+
+
 .. _manager: setup.html
diff --git a/Resources/doc/dsl/aggregations/index.rst b/Resources/doc/dsl/aggregations/index.rst
@@ -0,0 +1,4 @@
+Aggregations
+------------
+
+Coming soon...
diff --git a/Resources/doc/dsl/filters/index.rst b/Resources/doc/dsl/filters/index.rst
@@ -0,0 +1,4 @@
+Filters
+-------
+
+Coming soon...
diff --git a/Resources/doc/dsl/highlights/index.rst b/Resources/doc/dsl/highlights/index.rst
@@ -0,0 +1,4 @@
+Highlights
+----------
+
+Coming soon...
diff --git a/Resources/doc/dsl/index.rst b/Resources/doc/dsl/index.rst
@@ -96,3 +96,16 @@ It will create query:
         }
       }
     }
+
+Available API's
+---------------
+
+.. toctree::
+            :maxdepth: 10
+            :titlesonly:
+
+            queries/index
+            filters/index
+            aggregations/index
+            highlights/index
+            suggesters/index
diff --git a/Resources/doc/dsl/queries/index.rst b/Resources/doc/dsl/queries/index.rst
@@ -0,0 +1,4 @@
+Queries
+-------
+
+Coming soon...
diff --git a/Resources/doc/dsl/suggesters/index.rst b/Resources/doc/dsl/suggesters/index.rst
@@ -1,13 +1,21 @@
-Suggesters Usage
-================
+Suggesters
+==========
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+    :hidden:
+
+    types
+    indexed_suggesters
 
 `Suggesters`_ are used to find a similar looking term using the provided text.
 
 You can use suggesters (in any query, as you would normally) or `suggester api`_.
 
-There are basically four types of suggesters: terms, phrase, completion and context. To find out available parameters for these suggesters check out `<types.rst>`_ section.
+There are basically four types of suggesters: terms, phrase, completion and context. To find out available parameters for these suggesters check out `types <types.html>`_ section.
 
-.. note:: Completion and context suggesters need indexed data in order to work. To find out how to setup indexing and mapping, check `<indexed_suggesters.rst>`_ section.
+.. note:: Completion and context suggesters need indexed data in order to work. To find out how to setup indexing and mapping, check `indexed suggesters <indexed_suggesters.html>`_ section.
 
 Using Suggesters in Any Query
 -----------------------------
diff --git a/Resources/doc/dsl/suggesters/indexed_suggesters.rst b/Resources/doc/dsl/suggesters/indexed_suggesters.rst
diff --git a/Resources/doc/dsl/suggesters/types.rst b/Resources/doc/dsl/suggesters/types.rst
diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst
@@ -1,5 +1,5 @@
-ONGR Elasticsearch Bundle
-=========================
+Elasticsearch Bundle
+====================
 
 Installation
 ------------
@@ -24,7 +24,7 @@ Main things you should know while working with this bundle.
     commands
     mapping
     usage
-    searching
+    dsl/index
 
 Cookbook
 --------
@@ -33,9 +33,7 @@ More specific features and usages that you might need.
 
 .. toctree::
     :maxdepth: 1
-    :glob:
     :titlesonly:
     
     inheritance
-    suggesters/*
     warmers
diff --git a/Resources/doc/setup.rst b/Resources/doc/setup.rst
@@ -4,7 +4,7 @@ Setup
 Step 1: Install Elasticsearch bundle
 ------------------------------------
 
-Elasticsearch bundle is installed using `Composer`_.
+Elasticsearch bundle is installed using `Composer <https://getcomposer.org>`_.
 
 .. code:: bash
 
@@ -67,7 +67,7 @@ Add minimal configuration for Elasticsearch bundle.
                 mappings:
                     - AcmeStoreBundle
 
-.. note:: This is the basic example only, for more information about mapping, please take a look at `<mapping>`_ chapter.
+.. note:: This is the basic example only, for more information about mapping, please take a look at `mapping <mapping.html>`_ chapter.
 
 In this particular example we defined connections and managers. As you noticed it could be combined together.
 
@@ -116,7 +116,7 @@ Elasticsearch bundle uses ``Document`` objects to communicate with elasticsearch
         // ...
     }
 
-.. note:: This is the basic example only, for more information about mapping, please take a look at `<mapping>`_ chapter.
+.. note:: This is the basic example only, for more information about mapping, please take a look at `mapping <mapping.html>`_ chapter.
 
 Step 6: Create index
 --------------------
@@ -127,11 +127,10 @@ Elasticsearch bundle provides several ``CLI`` commands. One of them is for creat
 
     app/console es:index:create
 
-.. note:: More about the rest of the commands can be found in `<commands>`_ chapter.
+.. note:: More about the rest of the commands can be found in `commands <commands.html>`_ chapter.
 
 Step 7: Use your new bundle
 ---------------------------
 
-Usage documentation for the Elasticsearch bundle is available in `<usage.rst>`_.
+Usage documentation for the Elasticsearch bundle is available `here <usage.html>`_.
 
-.. _Composer: https://getcomposer.org
diff --git a/Resources/doc/usage.rst b/Resources/doc/usage.rst
@@ -12,7 +12,7 @@ Once you define managers in your ``config.yml`` file, you can use them in contro
 
     $manager = $this->get('es.manager');
 
-.. note:: More about how to setup managers can be found in `<mapping.rst>`_ chapter.
+.. note:: More about how to setup managers can be found in `mapping <mapping.html>`_ chapter.
 
 Create new document
 ~~~~~~~~~~~~~~~~~~~
@@ -90,4 +90,4 @@ There is also a findBy function which searches using Terms query:
     $repository = $manager->getRepository('AcmeTestBundle:Customer');
     $documents = $repository->findBy(['title' => 'Acme']);
 
-To perform a more complex queries there is a Search DSL API. Read more about it in `<searching.rst>`_ chapter.
+To perform a more complex queries there is a Search DSL API. Read more about it in `Searching via DSL <dsl/index.html>`_ chapter.
diff --git a/Resources/doc/warmers.rst b/Resources/doc/warmers.rst
@@ -41,16 +41,16 @@ Then register as a service (in this example yaml):
         vendor_bundle.foo.warmer:
             class: Vendor\Bundle\Warmer\FooWarmer
             tags:
-                - { name: es.warmer, connection: "default,bar" }
+                - { name: es.warmer, manager: "default,bar" }
 
-As you notice we can define multiple connections to load warmers to,
+As you notice we can define multiple managers to load warmers to,
 just be sure they are separated by commas and all surrounded by
 quotations marks.
 
 Putting warmers into index.
 ---------------------------
 
-The easiet way to load warmers are through `<commands.rst>`_.
+The easiet way to load warmers are through `commands <commands.html#warmer-put>`_.
 
 Also we can load them manually. f.e.
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +Aggregations
 +------------
++
 +Coming soon...
Original file line number	Diff line number	Diff line change
`@@ -96,3 +96,16 @@ It will create query:`
`96`	`96`	`}`
`97`	`97`	`}`
`98`	`98`	`}`
	`99`	`+`
	`100`	`+Available API's`
	`101`	`+---------------`
	`102`	`+`
	`103`	`+.. toctree::`
	`104`	`+ :maxdepth: 10`
	`105`	`+ :titlesonly:`
	`106`	`+`
	`107`	`+ queries/index`
	`108`	`+ filters/index`
	`109`	`+ aggregations/index`
	`110`	`+ highlights/index`
	`111`	`+ suggesters/index`