-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
minor #273 Add documentation (sstok)
This PR was merged into the 2.0-dev branch. Discussion ---------- | Q | A | ------------- | --- | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT Move documentation from https://github.com/rollerworks/search-docs to this repository, for easier maintenance and synchronization. Commits ------- 716d23a Add documentation
- Loading branch information
Showing
70 changed files
with
6,476 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
/_build/doctrees | ||
/_build/html | ||
*.pyc | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
This project's code-of-conduct can be found at https://github.com/rollerworks/contributing/blob/master/CODE_OF_CONDUCT.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
FROM python:2-stretch as builder | ||
|
||
WORKDIR /www | ||
|
||
COPY ./_build/.requirements.txt _build/ | ||
|
||
RUN pip install pip==9.0.1 wheel==0.29.0 \ | ||
&& pip install -r _build/.requirements.txt | ||
|
||
COPY . /www | ||
|
||
RUN make html | ||
|
||
FROM nginx:latest | ||
|
||
COPY --from=builder /www/_build/html /usr/share/nginx/html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,153 @@ | ||
# Makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line. | ||
SPHINXOPTS = | ||
SPHINXBUILD = sphinx-build | ||
PAPER = | ||
BUILDDIR = _build | ||
|
||
# Internal variables. | ||
PAPEROPT_a4 = -D latex_paper_size=a4 | ||
PAPEROPT_letter = -D latex_paper_size=letter | ||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | ||
# the i18n builder cannot share the environment and doctrees with the others | ||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | ||
|
||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext | ||
|
||
help: | ||
@echo "Please use \`make <target>' where <target> is one of" | ||
@echo " html to make standalone HTML files" | ||
@echo " dirhtml to make HTML files named index.html in directories" | ||
@echo " singlehtml to make a single large HTML file" | ||
@echo " pickle to make pickle files" | ||
@echo " json to make JSON files" | ||
@echo " htmlhelp to make HTML files and a HTML help project" | ||
@echo " qthelp to make HTML files and a qthelp project" | ||
@echo " devhelp to make HTML files and a Devhelp project" | ||
@echo " epub to make an epub" | ||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" | ||
@echo " latexpdf to make LaTeX files and run them through pdflatex" | ||
@echo " text to make text files" | ||
@echo " man to make manual pages" | ||
@echo " texinfo to make Texinfo files" | ||
@echo " info to make Texinfo files and run them through makeinfo" | ||
@echo " gettext to make PO message catalogs" | ||
@echo " changes to make an overview of all changed/added/deprecated items" | ||
@echo " linkcheck to check all external links for integrity" | ||
@echo " doctest to run all doctests embedded in the documentation (if enabled)" | ||
|
||
clean: | ||
-rm -rf $(BUILDDIR)/* | ||
|
||
html: | ||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html | ||
@echo | ||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html." | ||
|
||
dirhtml: | ||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml | ||
@echo | ||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." | ||
|
||
singlehtml: | ||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml | ||
@echo | ||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." | ||
|
||
pickle: | ||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle | ||
@echo | ||
@echo "Build finished; now you can process the pickle files." | ||
|
||
json: | ||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json | ||
@echo | ||
@echo "Build finished; now you can process the JSON files." | ||
|
||
htmlhelp: | ||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp | ||
@echo | ||
@echo "Build finished; now you can run HTML Help Workshop with the" \ | ||
".hhp project file in $(BUILDDIR)/htmlhelp." | ||
|
||
qthelp: | ||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp | ||
@echo | ||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \ | ||
".qhcp project file in $(BUILDDIR)/qthelp, like this:" | ||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/RollerworksRecordFilterBundle.qhcp" | ||
@echo "To view the help file:" | ||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/RollerworksRecordFilterBundle.qhc" | ||
|
||
devhelp: | ||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp | ||
@echo | ||
@echo "Build finished." | ||
@echo "To view the help file:" | ||
@echo "# mkdir -p $$HOME/.local/share/devhelp/RollerworksRecordFilterBundle" | ||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/RollerworksRecordFilterBundle" | ||
@echo "# devhelp" | ||
|
||
epub: | ||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub | ||
@echo | ||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub." | ||
|
||
latex: | ||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
@echo | ||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." | ||
@echo "Run \`make' in that directory to run these through (pdf)latex" \ | ||
"(use \`make latexpdf' here to do that automatically)." | ||
|
||
latexpdf: | ||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
@echo "Running LaTeX files through pdflatex..." | ||
$(MAKE) -C $(BUILDDIR)/latex all-pdf | ||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." | ||
|
||
text: | ||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text | ||
@echo | ||
@echo "Build finished. The text files are in $(BUILDDIR)/text." | ||
|
||
man: | ||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man | ||
@echo | ||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man." | ||
|
||
texinfo: | ||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo | ||
@echo | ||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." | ||
@echo "Run \`make' in that directory to run these through makeinfo" \ | ||
"(use \`make info' here to do that automatically)." | ||
|
||
info: | ||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo | ||
@echo "Running Texinfo files through makeinfo..." | ||
make -C $(BUILDDIR)/texinfo info | ||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." | ||
|
||
gettext: | ||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale | ||
@echo | ||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." | ||
|
||
changes: | ||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes | ||
@echo | ||
@echo "The overview file is in $(BUILDDIR)/changes." | ||
|
||
linkcheck: | ||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | ||
@echo | ||
@echo "Link check complete; look for any errors in the above output " \ | ||
"or in $(BUILDDIR)/linkcheck/output.txt." | ||
|
||
doctest: | ||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest | ||
@echo "Testing of doctests in the sources finished, look at the " \ | ||
"results in $(BUILDDIR)/doctest/output.txt." |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
alabaster==0.7.10 | ||
Babel==2.4.0 | ||
docutils==0.13.1 | ||
imagesize==0.7.1 | ||
Jinja2==2.9.6 | ||
MarkupSafe==1.0 | ||
Pygments==2.2.0 | ||
pytz==2017.2 | ||
requests==2.12.5 | ||
six==1.10.0 | ||
snowballstemmer==1.2.1 | ||
Sphinx==1.3.6 | ||
git+https://github.com/fabpot/sphinx-php.git@7312eccce9465640752e51373a480da700e02345#egg_name=sphinx-php |
Submodule _exts
added at
f1b69d
Submodule rollerworks
added at
2c509d
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
Composing SearchConditions | ||
========================== | ||
|
||
In this chapter you will learn how to compose your SearchConditions, without | ||
using an input processor. Composing Conditions manually is perfect for testing | ||
your integration, or using RollerworksSearch as a SDK for (REST) APIs. | ||
|
||
Creating a FieldSet | ||
------------------- | ||
|
||
Before you can compose a SearchCondition you first need a FieldSet configuration, | ||
even when using the Condition ony for exporting you need a FieldSet as the exporter | ||
needs to know which data transformer(s) to use. | ||
|
||
.. include:: fieldset.rst.inc | ||
|
||
And now you can use the FieldSet for the SearchConditionBuilder, note that | ||
values must be provided in the "model" format of the field-type. | ||
|
||
For the DateTimeType this is a ``DateTime`` object, for the id this is an | ||
``integer``, and username is simply a ``string``. | ||
|
||
For this example we want to search for users: | ||
|
||
Registered between the years 2015 and 2016 (but not within the month May) | ||
*or* have a username which contains the word "admin". | ||
|
||
.. code-block:: php | ||
use Rollerworks\Component\Search\ConditionOptimizer\DuplicateRemover; | ||
use Rollerworks\Component\Search\SearchConditionBuilder; | ||
use Rollerworks\Component\Search\Test\SearchConditionOptimizerTestCase; | ||
use Rollerworks\Component\Search\Value\Compare; | ||
use Rollerworks\Component\Search\Value\ExcludedRange; | ||
use Rollerworks\Component\Search\Value\PatternMatch; | ||
use Rollerworks\Component\Search\Value\Range; | ||
use Rollerworks\Component\Search\Value\ValuesBag; | ||
use Rollerworks\Component\Search\Value\ValuesGroup; | ||
$condition = SearchConditionBuilder::create($fieldSet, ValuesGroup::GROUP_LOGICAL_OR) | ||
->field('regDate') | ||
->add(new Range(new DateTime('2015-01-01 00:00:00 UTC'), new DateTime('2017-01-01 00:00:00 UTC'), true, false)) | ||
->add(new ExcludedRange(new DateTime('2015-03-01 00:00:00 UTC'), new DateTime('2015-04-01 00:00:00 UTC'), true, false)) | ||
end() | ||
->field('name') | ||
->add(new PatternMatch('admin', PatternMatch::PATTERN_CONTAINS)) | ||
->end() | ||
->getSearchCondition(); | ||
Lets break this down, ``field('name')`` tells the builder we want to work on | ||
a SearchField named ``name``. Once we are done we call ``end`` and return back to | ||
the ValuesGroup were we can add/remove other fields, and add new/remove (sub)groups. | ||
|
||
.. code-block:: php | ||
new Range(new DateTime('2015-01-01 00:00:00 UTC'), new DateTime('2017-01-01 00:00:00 UTC'), true, false) | ||
This code segment creates a new ``Range`` value value-holder with an inclusive | ||
lower bound and exclusive upper bound (everything lower then the value itself). | ||
|
||
.. note:: | ||
|
||
Calling ``field('name')`` multiple times will return the same instance | ||
of the ``ValuesBagBuilder``. Use ``field('name', true)`` to overwrite | ||
the existing instance. | ||
|
||
The ``SearchConditionBuilder`` is really powerful and developer friendly, but | ||
instead of explaining everything, the following full example should give you an | ||
idea about whats possible:: | ||
|
||
use Rollerworks\Component\Search\ConditionOptimizer\DuplicateRemover; | ||
use Rollerworks\Component\Search\SearchConditionBuilder; | ||
use Rollerworks\Component\Search\Test\SearchConditionOptimizerTestCase; | ||
use Rollerworks\Component\Search\Value\Compare; | ||
use Rollerworks\Component\Search\Value\ExcludedRange; | ||
use Rollerworks\Component\Search\Value\PatternMatch; | ||
use Rollerworks\Component\Search\Value\Range; | ||
use Rollerworks\Component\Search\Value\ValuesBag; | ||
use Rollerworks\Component\Search\Value\ValuesGroup; | ||
|
||
$condition = SearchConditionBuilder::create($fieldSet, ValuesGroup::GROUP_LOGICAL_OR) | ||
->field('regDate') | ||
->add(new Range(new DateTime('2015-01-01 00:00:00 UTC'), new DateTime('2017-01-01 00:00:00 UTC'), true, false)) | ||
->add(new ExcludedRange(new DateTime('2015-03-01 00:00:00 UTC'), new DateTime('2015-04-01 00:00:00 UTC'), true, false)) | ||
end() | ||
->field('name') | ||
->add(new PatternMatch('admin', PatternMatch::PATTERN_CONTAINS)) | ||
->end() | ||
->group() | ||
->field('id') | ||
->addSimpleValue(2) | ||
->addSimpleValue(5) | ||
->add(new Compare(10, '>')) | ||
->end() | ||
->group(ValuesGroup::GROUP_LOGICAL_OR) | ||
->field('first-name') | ||
->addSimpleValue('homer') | ||
->add(new PatternMatch('spider', PatternMatch::PATTERN_CONTAINS)) | ||
->add(new PatternMatch('pig', PatternMatch::PATTERN_CONTAINS)) | ||
->add(new PatternMatch('doctor', PatternMatch::PATTERN_STARTS_WITH, true)) // case-insensitive match | ||
->add(new PatternMatch('who', PatternMatch::PATTERN_CONTAINS, true)) // case-insensitive match | ||
->end() | ||
->end() | ||
->end() | ||
->getSearchCondition(); | ||
|
||
You can group as deep as needed, and always return to the previous level using ``end()``. | ||
The builder support all of your complex and simple conditions. | ||
|
||
See also :doc:`searching_in_practice` | ||
|
||
Further reading | ||
--------------- | ||
|
||
* :doc:`Visual condition builder <visual_condition_builder>` (coming soon) | ||
* :doc:`reference/exporters` | ||
|
Oops, something went wrong.