From 89a558e73589ab0b517f2b385cf185e8c9b25c18 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Sat, 29 Dec 2018 18:44:38 +0100 Subject: [PATCH] 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 | 4 +-- Documentation/source/changelog.rst | 18 ++-------- Documentation/source/changelog/0.0.8.rst | 16 +++++++++ .../20180306-120-facet-configuration.rst | 0 .../20180308-131-respect-page-cache-clear.rst | 0 .../20180308-introduce-php70-type-hints.rst | 0 .../20180309-25-provide-sys-language-uid.rst | 0 ...15-134-make-conent-fields-configurable.rst | 0 .../20180410-148-keep-sys_language_uid.rst | 0 ...t-relation-resolver-to-data-processing.rst | 0 ...180518-75-make-index-name-configurable.rst | 0 ...-allow-zero-as-typoscript-filter-value.rst | 0 ...e-pluginname-in-configurationcontainer.rst | 0 Documentation/source/changelog/0.1.0.rst | 15 ++++++++ .../2018-added-content-element-wizard.rst | 5 +++ .../0.1.0/2018-changed-interfaces.rst | 31 ++++++++++++++++ .../0.1.0/2018-elasticsearch-upgrade.rst | 9 +++++ .../0.1.0/2018-search-service-interface.rst | 23 ++++++++++++ .../20181027-added-flush-command.rst | 0 ...81027-allow-multiple-identifier-on-cli.rst | 13 +++++++ .../20181027-remove-cms7-support.rst | 4 +-- .../20181028-fluid-templating-list-items.rst | 28 +++++++++++++++ ...20181227-rename-of-configuration-files.rst | 6 ++++ ...81027-allow-multiple-identifier-on-cli.rst | 4 --- .../20181028-fluid-templating-list-items.rst | 24 ------------- Documentation/source/configuration.rst | 4 +-- Documentation/source/usage.rst | 35 ++++++++++++++----- 27 files changed, 182 insertions(+), 57 deletions(-) create mode 100644 Documentation/source/changelog/0.0.8.rst rename Documentation/source/changelog/{ => 0.0.8}/20180306-120-facet-configuration.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180308-131-respect-page-cache-clear.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180308-introduce-php70-type-hints.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180309-25-provide-sys-language-uid.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180315-134-make-conent-fields-configurable.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180410-148-keep-sys_language_uid.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180424-149-extract-relation-resolver-to-data-processing.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180518-75-make-index-name-configurable.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20180926-163-allow-zero-as-typoscript-filter-value.rst (100%) rename Documentation/source/changelog/{ => 0.0.8}/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer.rst (100%) create mode 100644 Documentation/source/changelog/0.1.0.rst create mode 100644 Documentation/source/changelog/0.1.0/2018-added-content-element-wizard.rst create mode 100644 Documentation/source/changelog/0.1.0/2018-changed-interfaces.rst create mode 100644 Documentation/source/changelog/0.1.0/2018-elasticsearch-upgrade.rst create mode 100644 Documentation/source/changelog/0.1.0/2018-search-service-interface.rst rename Documentation/source/changelog/{ => 0.1.0}/20181027-added-flush-command.rst (100%) create mode 100644 Documentation/source/changelog/0.1.0/20181027-allow-multiple-identifier-on-cli.rst rename Documentation/source/changelog/{ => 0.1.0}/20181027-remove-cms7-support.rst (56%) create mode 100644 Documentation/source/changelog/0.1.0/20181028-fluid-templating-list-items.rst create mode 100644 Documentation/source/changelog/0.1.0/20181227-rename-of-configuration-files.rst delete mode 100644 Documentation/source/changelog/20181027-allow-multiple-identifier-on-cli.rst delete mode 100644 Documentation/source/changelog/20181028-fluid-templating-list-items.rst diff --git a/Classes/Command/IndexCommandController.php b/Classes/Command/IndexCommandController.php index 8e1f370..dff0fb3 100644 --- a/Classes/Command/IndexCommandController.php +++ b/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.'); }); } diff --git a/Documentation/source/changelog.rst b/Documentation/source/changelog.rst index 9d226f7..fadb7d2 100644 --- a/Documentation/source/changelog.rst +++ b/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 diff --git a/Documentation/source/changelog/0.0.8.rst b/Documentation/source/changelog/0.0.8.rst new file mode 100644 index 0000000..03ce022 --- /dev/null +++ b/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 diff --git a/Documentation/source/changelog/20180306-120-facet-configuration.rst b/Documentation/source/changelog/0.0.8/20180306-120-facet-configuration.rst similarity index 100% rename from Documentation/source/changelog/20180306-120-facet-configuration.rst rename to Documentation/source/changelog/0.0.8/20180306-120-facet-configuration.rst diff --git a/Documentation/source/changelog/20180308-131-respect-page-cache-clear.rst b/Documentation/source/changelog/0.0.8/20180308-131-respect-page-cache-clear.rst similarity index 100% rename from Documentation/source/changelog/20180308-131-respect-page-cache-clear.rst rename to Documentation/source/changelog/0.0.8/20180308-131-respect-page-cache-clear.rst diff --git a/Documentation/source/changelog/20180308-introduce-php70-type-hints.rst b/Documentation/source/changelog/0.0.8/20180308-introduce-php70-type-hints.rst similarity index 100% rename from Documentation/source/changelog/20180308-introduce-php70-type-hints.rst rename to Documentation/source/changelog/0.0.8/20180308-introduce-php70-type-hints.rst diff --git a/Documentation/source/changelog/20180309-25-provide-sys-language-uid.rst b/Documentation/source/changelog/0.0.8/20180309-25-provide-sys-language-uid.rst similarity index 100% rename from Documentation/source/changelog/20180309-25-provide-sys-language-uid.rst rename to Documentation/source/changelog/0.0.8/20180309-25-provide-sys-language-uid.rst diff --git a/Documentation/source/changelog/20180315-134-make-conent-fields-configurable.rst b/Documentation/source/changelog/0.0.8/20180315-134-make-conent-fields-configurable.rst similarity index 100% rename from Documentation/source/changelog/20180315-134-make-conent-fields-configurable.rst rename to Documentation/source/changelog/0.0.8/20180315-134-make-conent-fields-configurable.rst diff --git a/Documentation/source/changelog/20180410-148-keep-sys_language_uid.rst b/Documentation/source/changelog/0.0.8/20180410-148-keep-sys_language_uid.rst similarity index 100% rename from Documentation/source/changelog/20180410-148-keep-sys_language_uid.rst rename to Documentation/source/changelog/0.0.8/20180410-148-keep-sys_language_uid.rst diff --git a/Documentation/source/changelog/20180424-149-extract-relation-resolver-to-data-processing.rst b/Documentation/source/changelog/0.0.8/20180424-149-extract-relation-resolver-to-data-processing.rst similarity index 100% rename from Documentation/source/changelog/20180424-149-extract-relation-resolver-to-data-processing.rst rename to Documentation/source/changelog/0.0.8/20180424-149-extract-relation-resolver-to-data-processing.rst diff --git a/Documentation/source/changelog/20180518-75-make-index-name-configurable.rst b/Documentation/source/changelog/0.0.8/20180518-75-make-index-name-configurable.rst similarity index 100% rename from Documentation/source/changelog/20180518-75-make-index-name-configurable.rst rename to Documentation/source/changelog/0.0.8/20180518-75-make-index-name-configurable.rst diff --git a/Documentation/source/changelog/20180926-163-allow-zero-as-typoscript-filter-value.rst b/Documentation/source/changelog/0.0.8/20180926-163-allow-zero-as-typoscript-filter-value.rst similarity index 100% rename from Documentation/source/changelog/20180926-163-allow-zero-as-typoscript-filter-value.rst rename to Documentation/source/changelog/0.0.8/20180926-163-allow-zero-as-typoscript-filter-value.rst diff --git a/Documentation/source/changelog/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer.rst b/Documentation/source/changelog/0.0.8/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer.rst similarity index 100% rename from Documentation/source/changelog/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer.rst rename to Documentation/source/changelog/0.0.8/20181106-170-do-not-specify-the-pluginname-in-configurationcontainer.rst diff --git a/Documentation/source/changelog/0.1.0.rst b/Documentation/source/changelog/0.1.0.rst new file mode 100644 index 0000000..036a222 --- /dev/null +++ b/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 diff --git a/Documentation/source/changelog/0.1.0/2018-added-content-element-wizard.rst b/Documentation/source/changelog/0.1.0/2018-added-content-element-wizard.rst new file mode 100644 index 0000000..4fc2dac --- /dev/null +++ b/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. diff --git a/Documentation/source/changelog/0.1.0/2018-changed-interfaces.rst b/Documentation/source/changelog/0.1.0/2018-changed-interfaces.rst new file mode 100644 index 0000000..993b7da --- /dev/null +++ b/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. + + diff --git a/Documentation/source/changelog/0.1.0/2018-elasticsearch-upgrade.rst b/Documentation/source/changelog/0.1.0/2018-elasticsearch-upgrade.rst new file mode 100644 index 0000000..bfc7e45 --- /dev/null +++ b/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. diff --git a/Documentation/source/changelog/0.1.0/2018-search-service-interface.rst b/Documentation/source/changelog/0.1.0/2018-search-service-interface.rst new file mode 100644 index 0000000..056bcb3 --- /dev/null +++ b/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; + } diff --git a/Documentation/source/changelog/20181027-added-flush-command.rst b/Documentation/source/changelog/0.1.0/20181027-added-flush-command.rst similarity index 100% rename from Documentation/source/changelog/20181027-added-flush-command.rst rename to Documentation/source/changelog/0.1.0/20181027-added-flush-command.rst diff --git a/Documentation/source/changelog/0.1.0/20181027-allow-multiple-identifier-on-cli.rst b/Documentation/source/changelog/0.1.0/20181027-allow-multiple-identifier-on-cli.rst new file mode 100644 index 0000000..952e12f --- /dev/null +++ b/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. diff --git a/Documentation/source/changelog/20181027-remove-cms7-support.rst b/Documentation/source/changelog/0.1.0/20181027-remove-cms7-support.rst similarity index 56% rename from Documentation/source/changelog/20181027-remove-cms7-support.rst rename to Documentation/source/changelog/0.1.0/20181027-remove-cms7-support.rst index ec493f1..e62d50e 100644 --- a/Documentation/source/changelog/20181027-remove-cms7-support.rst +++ b/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. diff --git a/Documentation/source/changelog/0.1.0/20181028-fluid-templating-list-items.rst b/Documentation/source/changelog/0.1.0/20181028-fluid-templating-list-items.rst new file mode 100644 index 0000000..7094ff2 --- /dev/null +++ b/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: + + + + + Add opening for possible different partials based on Document types: + + + {f:render(partial: 'resultItem-{result.search_document_type}', arguments: {result: result)} + + + // Render pages + + + + // Render custom "documentType" + + + diff --git a/Documentation/source/changelog/0.1.0/20181227-rename-of-configuration-files.rst b/Documentation/source/changelog/0.1.0/20181227-rename-of-configuration-files.rst new file mode 100644 index 0000000..2aa71d8 --- /dev/null +++ b/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. diff --git a/Documentation/source/changelog/20181027-allow-multiple-identifier-on-cli.rst b/Documentation/source/changelog/20181027-allow-multiple-identifier-on-cli.rst deleted file mode 100644 index bab4211..0000000 --- a/Documentation/source/changelog/20181027-allow-multiple-identifier-on-cli.rst +++ /dev/null @@ -1,4 +0,0 @@ -Feature "Allow multiple identifiers on cli" -=========================================== - -All CLI commands except a comma separated list of IDs now. diff --git a/Documentation/source/changelog/20181028-fluid-templating-list-items.rst b/Documentation/source/changelog/20181028-fluid-templating-list-items.rst deleted file mode 100644 index 0550180..0000000 --- a/Documentation/source/changelog/20181028-fluid-templating-list-items.rst +++ /dev/null @@ -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: - - - - - Add opening for possible different partials based on Document types: - - - - {f:render(partial: 'Results/Item/YourDocumentType', arguments: {result: result})} - {f:render(partial: 'Results/Item/Page', arguments: {result: result})} - {f:render(partial: 'Results/Item/Unknown', arguments: {result: result})} - - - diff --git a/Documentation/source/configuration.rst b/Documentation/source/configuration.rst index 53ac469..7891008 100644 --- a/Documentation/source/configuration.rst +++ b/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 diff --git a/Documentation/source/usage.rst b/Documentation/source/usage.rst index fc6d08a..8e0d93c 100644 --- a/Documentation/source/usage.rst +++ b/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: