update docs

Author: Gerit Wagner

README.md

@@ -16,124 +16,6 @@ As a default it relies on the JSON schema proposed by an expert panel (Haddaway
 The package can be used programmatically or through the command line, has zero dependencies, and can therefore be integrated in a variety of environments.
 The heuristics, parsers, and linters are battle-tested on over 500 peer-reviewed queries registered at [searchRxiv](https://www.cabidigitallibrary.org/journal/searchrxiv).
 
-## Installation
-
-To install search-query, run:
-
-```
-pip install search-query
-```
-
-## Programmatic use
-
-To create a query programmatically, run:
-
-```Python
-from search_query import OrQuery, AndQuery
-
-# Typical building-blocks approach
-digital_synonyms = OrQuery(["digital", "virtual", "online"], search_field="Abstract")
-work_synonyms = OrQuery(["work", "labor", "service"], search_field="Abstract")
-query = AndQuery([digital_synonyms, work_synonyms], search_field="Author Keywords")
-```
-
-Parameters:
-
-- list of strings or queries: strings that you want to include in the search query,
-- `search_field`: search field to which the query should be applied (available options: TODO: GIVE EXAMPLES AND LINK TO DOCS)
-
-To load a JSON query file, run the parser:
-
-```python
-from search_query.search_file import SearchFile
-from search_query.parser import parse
-
-search = SearchFile("search-file.json")
-query = parse(search.search_string, syntax=search.platform)
-```
-
-Available platform identifiers are listed [here](search_query/constants.py).
-
-To validate a JSON query file, run the linter:
-
-```Python
-from search_query.linter import run_linter
-
-messages = run_linter(search.search_string, syntax=search.platform)
-print(messages)
-```
-
-Linter messages are documented and explained [here](docs/dev_linter.md).
-
-To simplify and format a query, run:
-
-```Python
-query.format(*tbd: how to select/exclude rules?*)
-```
-To translate a query to a particular database syntax and print it, run:
-
-```Python
-query.to_string(syntax="ebsco")
-query.to_string(syntax="pubmed")
-query.to_string(syntax="wos")
-```
-
-To write a query to a JSON file, run the serializer:
-
-```Python
-from search_query import save_file
-
-save_file(
-    filename="search-file.json",
-    query_str=query.to_string(syntax="wos"),
-    syntax="wos",
-    authors=[{"name": "Tom Brady"}],
-    record_info={},
-    date={}
-)
-```
-
-## CLI use
-
-Linters can be run on the CLI:
-
-```
-search-query lint search-file.json
-```
-
-## Pre-commit hooks
-
-Linters can be included as pre-commit hooks by adding the following to the `.pre-commit-config.yaml:
-
-```yaml
-repos:
-  - repo: https://github.com/CoLRev-Environment/search-query
-    rev: main # or version of search-query
-    hooks:
-      - id: search-file-lint
-
-```
-
-For development and testing, use the following:
-
-```yaml
-repos:
-  - repo: local
-    hooks:
-      - id: search-file-lint
-        name: Search-file linter
-        entry: search-file-lint
-        language: python
-        files: \.json$
-```
-
-To activate and run:
-
-```
-pre-commit install
-pre-commit run --all
-```
-
 ## Documentation
 
 [docs](docs/readme.md)

docs/source/documentation.png docs/source/dev_docs/documentation.pngdocs/source/documentation.png renamed to docs/source/dev_docs/documentation.png

@@ -1,7 +1,29 @@
 Developing a parser
 ===================
 
-A code skeleton is available for the `parser <parser_skeleton.py>`_ and `tests <parser_skeleton_tests.py>`_.
+.. image:: documentation.png
+   :width: 800px
+
+Development setup
+-------------------
+
+.. code-block::
+   :caption: Installation in editable mode with `dev` extras
+
+   pip install -e ".[dev]"
+
+Skeleton
+--------------------
+
+A code skeleton is available for the parser and tests:
+
+.. literalinclude:: parser_skeleton.py
+   :language: python
+
+
+.. literalinclude:: parser_skeleton_tests.py
+   :language: python
+
 
 To parse a list format, the numbered sub-queries should be replaced to create a search string, which can be parsed with the standard string-parser. This helps to avoid redundant implementation.
 
@@ -30,3 +52,76 @@ When parsing combined DB-Fields, the standard syntax should consist of n nodes,
 **n:1 matches**
 
 If multiple Database-Fields correspond to the same Standard-Field, a combination of the default Database-Field and Standard-Field are added to the ``constants.SYNTAX_FIELD_MAP``. Non-default Database-Fields are replaced by the parser. For example, the default for MeSH terms at Pubmed is ``[mh]``, but the parser also supports ``[mesh]``.
+
+Search Field Validation in Strict vs. Non-Strict Modes
+----------------------------------------------------------
+
+.. list-table:: Search Field Validation in Strict vs. Non-Strict Modes
+   :widths: 20 20 20 20 20
+   :header-rows: 1
+
+   * - **Search-Field required**
+     - **Search String**
+     - **Search-Field**
+     - **Mode: Strict**
+     - **Mode: Non-Strict**
+   * - Yes
+     - With Search-Field
+     - Empty
+     - ok
+     - ok
+   * - Yes
+     - With Search-Field
+     - Equal to Search-String
+     - ok - search-field-redundant
+     - ok
+   * - Yes
+     - With Search-Field
+     - Different from Search-String
+     - error: search-field-contradiction
+     - ok - search-field-contradiction. Parser uses Search-String per default
+   * - Yes
+     - Without Search-Field
+     - Empty
+     - error: search-field-missing
+     - ok - search-field-missing. Parser adds `title` as the default
+   * - Yes
+     - Without Search-Field
+     - Given
+     - ok - search-field-extracted
+     - ok
+   * - No
+     - With Search-Field
+     - Empty
+     - ok
+     - ok
+   * - No
+     - With Search-Field
+     - Equal to Search-String
+     - ok - search-field-redundant
+     - ok
+   * - No
+     - With Search-Field
+     - Different from Search-String
+     - error: search-field-contradiction
+     - ok - search-field-contradiction. Parser uses Search-String per default
+   * - No
+     - Without Search-Field
+     - Empty
+     - ok - search-field-not-specified
+     - ok - Parser uses default of database
+   * - No
+     - Without Search-Field
+     - Given
+     - ok - search-field-extracted
+     - ok
+
+Tests
+----------------
+
+- All test data should be stored in standard JSON.
+
+Resources
+---------------
+
+- `Web of Science Errors <https://images.webofknowledge.com/WOKRS528R6/help/TCT/ht_errors.html>`_