Merge pull request netgen#88 from netgen/docs

NSA-1: Initial Read The Docs documentation

.gitignore

@@ -1,3 +1,4 @@
 /vendor/
 composer.lock
 .php_cs.cache
+docs/_build

README.md

@@ -1,6 +1,7 @@
 # Netgen's Site API for eZ Platform
 
 [![Build Status](https://img.shields.io/travis/netgen/ezplatform-site-api.svg?style=flat-square)](https://travis-ci.org/netgen/ezplatform-site-api)
+[![Read the Docs](https://img.shields.io/readthedocs/pip.svg?style=flat-square)](https://docs.netgen.io/projects/site-api/en/latest/)
 [![Code Coverage](https://img.shields.io/codecov/c/github/netgen/ezplatform-site-api.svg?style=flat-square)](https://codecov.io/gh/netgen/ezplatform-site-api)
 [![Quality Score](https://img.shields.io/scrutinizer/g/netgen/ezplatform-site-api.svg?style=flat-square)](https://scrutinizer-ci.com/g/netgen/ezplatform-site-api)
 [![Downloads](https://img.shields.io/packagist/dt/netgen/ezplatform-site-api.svg?style=flat-square)](https://packagist.org/packages/netgen/ezplatform-site-api)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = NetgenSiteAPI
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+
+import sys, os
+import sphinx_rtd_theme
+
+from sphinx.highlighting import lexers
+from pygments.lexers.web import PhpLexer
+from pygments.lexers.web import HtmlLexer
+from pygments.lexers.web import JsonLexer
+
+from datetime import datetime
+
+lexers['php'] = PhpLexer(startinline=True)
+lexers['php-annotations'] = PhpLexer(startinline=True)
+lexers['html'] = HtmlLexer(startinline=True)
+lexers['json'] = JsonLexer(startinline=True)
+
+extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.ifconfig',
+    'sensio.sphinx.configurationblock']
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = 'Netgen\'s Site API for eZ Platform'
+copyright = 'Netgen'
+author = 'Netgen'
+
+version = ''
+release = ''
+
+exclude_patterns = ['_build']
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+html_static_path = ['_static']
+templates_path = ['_templates']
+
+html_theme_options = {
+    'collapse_navigation': True,
+    'display_version': True,
+}
+
+html_context = {
+    'copyright_url': 'https://www.netgenlabs.com',
+    'current_year': datetime.utcnow().year
+}
+
+def setup(app):
+    app.add_stylesheet("css/style.css")

docs/index.rst

@@ -0,0 +1,22 @@
+Netgen's Site API for eZ Platform
+=================================
+
+Reference
+---------
+
+.. toctree::
+    :hidden:
+
+    reference/index
+
+.. include:: /reference/map.rst.inc
+
+Upgrades
+--------
+
+.. toctree::
+    :hidden:
+
+    upgrades/index
+
+.. include:: /upgrades/map.rst.inc

docs/reference/configuration.rst

@@ -0,0 +1,2 @@
+Configuration
+=============

docs/reference/index.rst

@@ -0,0 +1,12 @@
+Reference
+=========
+
+.. toctree::
+    :hidden:
+
+    installation_instructions
+    configuration
+    templating
+    query_types
+
+.. include:: /reference/map.rst.inc

docs/reference/installation_instructions.rst

@@ -0,0 +1,23 @@
+Installation instructions
+=========================
+
+To install Site API first add it as a dependency to your project:
+
+.. code-block:: shell
+
+    $ composer require netgen/ezplatform-site-api:^2.5
+
+Once Site API is installed, activate the bundle in ``app/AppKernel.php`` file by adding it to the
+``$bundles`` array in ``registerBundles()`` method, together with other required bundles:
+
+.. code-block:: php
+
+    public function registerBundles()
+    {
+        //...
+
+        $bundles[] = new Netgen\Bundle\EzPlatformSiteApiBundle\NetgenEzPlatformSiteApiBundle();
+        $bundles[] = new Netgen\Bundle\EzPlatformSearchExtraBundle\NetgenEzPlatformSearchExtraBundle;
+
+        return $bundles;
+    }

docs/reference/map.rst.inc

@@ -0,0 +1,4 @@
+* :doc:`/reference/installation_instructions`
+* :doc:`/reference/configuration`
+* :doc:`/reference/templating`
+* :doc:`/reference/query_types`

docs/reference/query_types.rst

@@ -0,0 +1,189 @@
+Query Types
+===========
+
+Site API Query Types expand upon Query Type feature from eZ Publish Kernel, using the same basic
+interfaces. That will enable using your existing Query Types, but how Site API integrates them with
+the rest of the system differs from eZ Publish Kernel.
+
+Built-in Query Types
+--------------------
+
+A number of generic Query Types is provided out of the box. We can separate these into three groups:
+
+General purpose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /reference/query_types/general_purpose_query_types.rst.inc
+
+Content relations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /reference/query_types/content_relations_query_types.rst.inc
+
+Location hierarchy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /reference/query_types/location_query_types.rst.inc
+
+Query Type configuration
+--------------------------------------------------------------------------------
+
+Query Types have their own semantic configuration under ``queries`` key in configuration for a
+particular Content view. Under this key separate queries are defined under their own identifier
+keys, which are later used to reference the configured query from the Twig templates.
+
+Available parameters and their default values are:
+
+- ``query_type`` - identifies the Query Type to be used
+- ``named_query`` - identifies named query to be used
+- ``max_per_page: 25`` - pagination parameter for maximum number of items per page
+- ``page: 1`` - pagination parameter for current page
+- ``use_filter: true`` - whether to use ``FilterService`` or ``FindService`` for executing the query
+- ``parameters: []`` - contains the actual Query Type parameters
+
+Parameters ``query_type`` and ``named_query`` are mutually exclusive, you are allowed to set only
+one or the other. But they are also mandatory - you will have to set one of them.
+
+Example below shows how described configuration looks in practice:
+
+.. code-block:: yaml
+
+    ezpublish:
+        system:
+            frontend_group:
+                ngcontent_view:
+                    full:
+                        category:
+                            template: '@ezdesign/content/full/category.html.twig'
+                            match:
+                                Identifier\ContentType: 'category'
+                            queries:
+                                children:
+                                    query_type: 'SiteAPI:Location/Children'
+                                    max_per_page: 10
+                                    page: 1
+                                    parameters:
+                                        content_type: 'article'
+                                        sort: 'published desc'
+                                related_images:
+                                    query_type: 'SiteAPI:Content/Relations/ForwardFields'
+                                    max_per_page: 10
+                                    page: 1
+                                    parameters:
+                                        content_type: 'article'
+                                        sort: 'published desc'
+                            params:
+                                ...
+
+
+.. note:: You can define unlimited number of queries on any controller.
+
+Named Query Type configuration
+------------------------------
+
+As hinted above with ``named_query`` parameter, it is possible to define "named queries", which can
+be referenced in query configuration for a particular content view. They are configured under
+``ng_named_query``, which is a top section of a siteaccess configuration, on the same level as
+``ng_content_view``:
+
+.. code-block:: yaml
+
+    ezpublish:
+        system:
+            frontend_group:
+                ng_named_query:
+                    children_named_query:
+                        query_type: 'SiteAPI:Location/Children'
+                        max_per_page: 10
+                        page: 1
+                        parameters:
+                            content_type: 'article'
+                            sort: 'published desc'
+                ngcontent_view:
+                    full:
+                        category:
+                            template: '@ezdesign/content/full/category.html.twig'
+                            match:
+                                Identifier\ContentType: 'category'
+                            queries:
+                                children: 'children_named_query'
+                                children_5_per_page:
+                                    named_query: 'children_named_query'
+                                    max_per_page: 5
+                                images:
+                                    named_query: 'children_named_query'
+                                    parameters:
+                                        content_type: 'image'
+                            params:
+                                ...
+
+.. note:: You can override some of the parameters from the referenced named query.
+
+You can notice that there are two ways of referencing a named query. In case when there are no other
+parameters, you can do it directly like this:.
+
+.. code-block:: yaml
+
+    queries:
+        children: 'children_named_query'
+
+The example above is really just a shortcut to the example below:
+
+.. code-block:: yaml
+
+    queries:
+        children:
+            named_query: 'children_named_query'
+
+You can also notice that it's possible to override parameters from the referenced named query. This
+is limited to first level keys from the main configuration and also first level keys under the
+``parameters`` key.
+
+Language expressions
+--------------------------------------------------------------------------------
+
+TODO
+
+Accessing the configured queries from Twig
+--------------------------------------------------------------------------------
+
+Configured queries will be available in Twig templates, through ``ng_query`` or ``ng_raw_query``.
+The difference it that the former will return a ``Pagerfanta`` instance, while the latter will
+return an instance of ``SerachResult``. That also means ``ng_query`` will use ``max_per_page`` and
+``page`` parameters to configure the pager, while ``ng_raw_query`` ignores them and executes the
+configured query directly.
+
+.. note:: Queries are only executed as you access them through ``ng_query`` or ``ng_raw_query``. If you don't call those functions on any of the configured queries, none of them will be executed.
+
+Both ``ng_query`` and ``ng_raw_query`` accept a single argument. This is the identifier of the
+query, which is the key under the ``queries`` section, under which the query is configured.
+
+Example usage of ``ng_query``:
+
+.. code-block:: twig
+
+    {% set images = ng_query( 'images' ) %}
+
+    <p>Total images: {{ images.nbResults }}</p>
+
+    {% for image in images %}
+        <p>{{ image.content.name }}</p>
+    {% endfor %}
+
+    {{ pagerfanta( images, 'twitter_bootstrap' ) }}
+
+Example usage of ``ng_raw_query``:
+
+.. code-block:: twig
+
+    {% set searchResult = ng_raw_query( 'categories' ) %}
+
+    {% for categoryHit in searchResult.searchHits %}
+        <p>{{ categoryHit.valueObject.content.name }}: {{ categoryHit.valueObject.score }}</p>
+    {% endfor %}
+
+.. note:: You can't execute named queries. They are only available for referencing in concrete query configuration for a particular view.
+
+.. note:: Execution of queries is **not cached**. If you call ``ng_query`` or ``ng_raw_query`` on the same query multiple times, the same query will be executed multiple times. You should store the result in a variable and reuse the variable instead.
+
+.. hint:: If you need to access the same query result multiple times, store it in a variable and instead access that variable.

docs/reference/query_types/content_fetch.rst

@@ -0,0 +1,27 @@
+General purpose Content fetch
+================================================================================
+
+This Query Type is used to build general purpose Location queries.
+
++-------------+------------------------------------------------------------------------------+
+| Identifier  | ``SiteAPI:Location/Fetch``                                                   |
++-------------+------------------------------------------------------------------------------+
+| Common      | - `content_type`_                                                            |
+| Content     | - `field`_                                                                   |
+| conditions  | - `publication_date`_                                                        |
+|             | - `section`_                                                                 |
+|             | - `state`_                                                                   |
++-------------+------------------------------------------------------------------------------+
+| Common      | - `limit`_                                                                   |
+| query       | - `offset`_                                                                  |
+| parameters  | - `sort`_                                                                    |
++-------------+------------------------------------------------------------------------------+
+
+.. | Class       | :class:`Netgen\\EzPlatformSiteApi\\Core\\Site\\QueryType\\Content\\Fetch`    |
+.. +-------------+------------------------------------------------------------------------------+
+
+Examples
+--------------------------------------------------------------------------------
+
+.. include:: /reference/query_types/parameters/common_content_parameters.rst.inc
+.. include:: /reference/query_types/parameters/common_query_parameters.rst.inc