TASK: Improve documentation

* Add some missing documentation.
* Adjust some documentation due to breaking changes.
* Adjust structure of documentation for easier changelog rendering and
  browsing.

Classes/Command/IndexCommandController.php

@@ -72,7 +72,7 @@ class IndexCommandController extends CommandController
     }
 
     /**
-     * Will delete the full index for given identifiers.
+     * Will flush the index for given identifiers from backend.
      *
      * @param string $identifier Comma separated list of identifiers.
      */
@@ -80,7 +80,7 @@ class IndexCommandController extends CommandController
     {
         $this->executeForIdentifier($identifiers, function (IndexerInterface $indexer) {
             $indexer->delete();
-            $this->outputLine('Indice ' . $indexer->getIdentifier() . ' was deleted.');
+            $this->outputLine('Indice ' . $indexer->getIdentifier() . ' was flushed.');
         });
     }
 

Documentation/source/changelog.rst

@@ -2,19 +2,7 @@ Changelog
 =========
 
 .. toctree::
-   :maxdepth: 1
-   :glob:
+   :maxdepth: 2
 
-   changelog/20181027-added-flush-command
-   changelog/20181027-allow-multiple-identifiers-on-cli
-   changelog/20181027-remove-cms7-support
-   changelog/20180518-75-make-index-name-configurable
-   changelog/20180424-149-extract-relation-resolver-to-data-processing
-   changelog/20180410-148-keep-sys_language_uid
-   changelog/20180315-134-make-conent-fields-configurable
-   changelog/20180309-25-provide-sys-language-uid
-   changelog/20180308-131-respect-page-cache-clear
-   changelog/20180308-introduce-php70-type-hints
-   changelog/20180306-120-facet-configuration
-   changelog/20180926-163-allow-zero-as-typoscript-filter-value
-   changelog/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer
+   changelog/0.1.0
+   changelog/0.0.8

Documentation/source/changelog/0.0.8.rst

@@ -0,0 +1,16 @@
+Up till v0.0.8
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   0.0.8/20180306-120-facet-configuration
+   0.0.8/20180308-131-respect-page-cache-clear
+   0.0.8/20180308-introduce-php70-type-hints
+   0.0.8/20180309-25-provide-sys-language-uid
+   0.0.8/20180315-134-make-conent-fields-configurable
+   0.0.8/20180410-148-keep-sys_language_uid
+   0.0.8/20180424-149-extract-relation-resolver-to-data-processing
+   0.0.8/20180518-75-make-index-name-configurable
+   0.0.8/20180926-163-allow-zero-as-typoscript-filter-value
+   0.0.8/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer

Documentation/source/changelog/0.1.0.rst

@@ -0,0 +1,15 @@
+v0.1.0
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   0.1.0/2018-added-content-element-wizard
+   0.1.0/2018-changed-interfaces
+   0.1.0/2018-elasticsearch-upgrade
+   0.1.0/2018-search-service-interface
+   0.1.0/20181027-added-flush-command
+   0.1.0/20181027-allow-multiple-identifier-on-cli
+   0.1.0/20181027-remove-cms7-support
+   0.1.0/20181028-fluid-templating-list-items
+   0.1.0/20181227-rename-of-configuration-files

Documentation/source/changelog/0.1.0/2018-added-content-element-wizard.rst

@@ -0,0 +1,5 @@
+Feature: "Added content element wizard entry"
+=============================================
+
+The search core plugin is now selectable from the content element wizard by default.
+Therefore the necessary PageTSConfig is added by default.

Documentation/source/changelog/0.1.0/2018-changed-interfaces.rst

@@ -0,0 +1,31 @@
+Breaking Change "Changed interfaces"
+====================================
+
+Some interfaces and abstract classes have been adjusted:
+
+``Codappix\SearchCore\Connection\ConnectionInterface``:
+
+   * New method ``public function deleteIndexByDocumentType(string $documentType);``
+
+``Codappix\SearchCore\Domain\Index\IndexerInterface``:
+
+   * New method ``public function deleteDocuments();``
+
+   * New method ``public function getIdentifier(): string;``
+
+``Codappix\SearchCore\Domain\Index\AbstractIndexer``:
+
+   * New method ``abstract public function getDocumentIdentifier($identifier): string;``
+
+``Codappix\SearchCore\Connection\SearchRequestInterface``:
+
+   * Changed method signature from ``public function setSearchService(SearchService $searchService);``
+     to ``public function setSearchService(SearchServiceInterface $searchService);``
+
+Also some exceptions have changed:
+
+* ``Codappix\SearchCore\Connection\Elasticsearch\DocumentFactory::getDocument()`` now
+throws an ``\InvalidArgumentException`` instead of ``\Exception``, if no
+``search_identifier`` was provided.
+
+

Documentation/source/changelog/0.1.0/2018-elasticsearch-upgrade.rst

@@ -0,0 +1,9 @@
+Breaking Change "Elasticsearch Upgrade"
+=======================================
+
+By now Elasticsearch v6.x is required in order to work.
+
+You might need to change some configuration, as this is just piped through to
+Elasticsearch. Check out the breaking changes of Elasticsearch from 5.x to 6.x.
+
+Also update your Elasticsearch instance.

Documentation/source/changelog/0.1.0/2018-search-service-interface.rst

@@ -0,0 +1,23 @@
+Feature "SearchServiceInterface"
+================================
+
+The concrete search service can now be exchanged. Therefore a new Interface was
+introduced::
+
+   namespace Codappix\SearchCore\Domain\Search;
+
+   use Codappix\SearchCore\Connection\SearchRequestInterface;
+   use Codappix\SearchCore\Connection\SearchResultInterface;
+
+   interface SearchServiceInterface
+   {
+      /**
+      * Fetches result for provided search request.
+      */
+      public function search(SearchRequestInterface $searchRequest): SearchResultInterface;
+
+      /**
+      * Processes the result, e.g. applies configured data processing to result.
+      */
+      public function processResult(SearchResultInterface $searchResult): SearchResultInterface;
+   }

Documentation/source/changelog/0.1.0/20181027-allow-multiple-identifier-on-cli.rst

@@ -0,0 +1,13 @@
+Breaking Change "Allow multiple identifiers on cli"
+===================================================
+
+All CLI commands except a comma separated list of IDs now. Still single IDs are allowed.
+
+Each Identifier will be processed one by another. This is just for continence to not
+call the command multiple times with different identifiers.
+
+Spaces are ignored before and after commas.
+
+
+As the argument was renamed from ``--identifier`` to ``--identifiers``, this is
+considered a breaking change.

Documentation/source/changelog/0.1.0/20181027-remove-cms7-support.rst

@@ -1,5 +1,5 @@
-Breaking Change "Remove CMS7 support"
-=====================================
+Breaking Change "Removed CMS7 support"
+======================================
 
 We no longer support TYPO3 CMS 7.x.
 

Documentation/source/changelog/0.1.0/20181028-fluid-templating-list-items.rst

@@ -0,0 +1,28 @@
+Feature "Added fluid partials for list items"
+=============================================
+
+When using a separate partial for ListItem you can simply adjust for your custom page type:
+
+Example ListItem.html::
+-----------------------
+.. code-block:: html
+    :linenos:
+
+    <html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
+          data-namespace-typo3-fluid="true">
+
+    <f:comment>
+        Add opening for possible different partials based on Document types:
+    </f:comment>
+
+    {f:render(partial: 'resultItem-{result.search_document_type}', arguments: {result: result)}
+
+    <f:section name="resultItem-pages">
+       // Render pages
+    </f:section>
+
+    <f:section name="resultItem-documentType">
+       // Render custom "documentType"
+    </f:section>
+
+    </html>

Documentation/source/changelog/0.1.0/20181227-rename-of-configuration-files.rst

@@ -0,0 +1,6 @@
+Breaking Change "Configuration files were renamed"
+==================================================
+
+TypoScript configuration files now end with ``.typoscript`` instead of ``.txt``.
+
+If you require these files via include statements with full file name, these need to be adjusted.

Documentation/source/changelog/20181027-allow-multiple-identifier-on-cli.rst

@@ -1,4 +0,0 @@
-Feature "Allow multiple identifiers on cli"
-===========================================
-
-All CLI commands except a comma separated list of IDs now.

Documentation/source/changelog/20181028-fluid-templating-list-items.rst

@@ -1,24 +0,0 @@
-Feature "Added fluid partials for list items"
-=============================================
-
-When using a seperate partial for ListItem you can simply adjust for your custom page type:
-
-Example ListItem.html::
------------------------
-.. code-block:: html
-    :linenos:
-
-    <html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
-          data-namespace-typo3-fluid="true">
-
-    <f:comment>
-        Add opening for possible different partials based on Document types:
-    </f:comment>
-
-    <f:switch expression="{result.search_document_type}">
-        <f:case value="your-document-type">{f:render(partial: 'Results/Item/YourDocumentType', arguments: {result: result})}</f:case>
-        <f:case value="pages">{f:render(partial: 'Results/Item/Page', arguments: {result: result})}</f:case>
-        <f:defaultCase>{f:render(partial: 'Results/Item/Unknown', arguments: {result: result})}</f:defaultCase>
-    </f:switch>
-
-    </html>

Documentation/source/configuration.rst

@@ -24,11 +24,11 @@ The structure is following TYPO3 Extbase conventions. All settings are placed in
 
 Here is the example default configuration that's provided through static include:
 
-.. literalinclude:: ../../Configuration/TypoScript/constants.txt
+.. literalinclude:: ../../Configuration/TypoScript/constants.typoscript
    :language: typoscript
    :caption: Static TypoScript Constants
 
-.. literalinclude:: ../../Configuration/TypoScript/setup.txt
+.. literalinclude:: ../../Configuration/TypoScript/setup.typoscript
    :language: typoscript
    :caption: Static TypoScript Setup
 

Documentation/source/usage.rst

@@ -11,12 +11,13 @@ Manual indexing
 
 You can trigger indexing from CLI::
 
-    ./typo3/cli_dispatch.phpsh extbase index:index --identifier 'pages'
-    ./bin/typo3cms index:index --identifier 'pages'
+    ./typo3/cli_dispatch.phpsh extbase index:index --identifiers 'pages'
+    ./bin/typo3cms index:index --identifiers 'pages'
 
 This will index the table ``pages`` using the :ref:`TcaIndexer`.
 
-Only one index per call is available, to run multiple indexers, just make multiple calls.
+Multiple indexer can be called by providing a comma separated list of identifiers as
+a single argument. Spaces before and after commas are ignored.
 The indexers have to be defined in TypoScript via :ref:`configuration_options_index`.
 
 .. _usage_manual_deletion:
@@ -24,14 +25,32 @@ The indexers have to be defined in TypoScript via :ref:`configuration_options_in
 Manual deletion
 ---------------
 
-You can trigger deletion for a single index from CLI::
+You can trigger deletion for indexes from CLI::
 
-    ./typo3/cli_dispatch.phpsh extbase index:delete --identifier 'pages'
-    ./bin/typo3cms index:delete --identifier 'pages'
+    ./typo3/cli_dispatch.phpsh extbase index:delete --identifiers 'pages'
+    ./bin/typo3cms index:delete --identifiers 'pages'
 
-This will delete the index for the table ``pages``.
+This will delete the index for the table ``pages``. Deletion means removing all
+documents from the index.
 
-Only one delete per call is available, to run multiple deletions, just make multiple calls.
+Multiple indices can be called by providing a comma separated list of identifiers as
+a single argument. Spaces before and after commas are ignored.
+
+.. _usage_manual_flush:
+
+Manual flush
+------------
+
+You can trigger flush for indexes from CLI::
+
+    ./typo3/cli_dispatch.phpsh extbase index:flush --identifiers 'pages'
+    ./bin/typo3cms index:flush --identifiers 'pages'
+
+This will flush the index for the table ``pages``. Flush means removing the index
+from backend.
+
+Multiple indices can be called by providing a comma separated list of identifiers as
+a single argument. Spaces before and after commas are ignored.
 
 .. _usage_auto_indexing: