Fix #21 Add Readthedocs Configuration (#26)

* Fix #21 Add Readthedocs Configuration

This moves all docs to the docs directory to setup for readthedocs
creation of the documentation for jsonpath2. This also moves tests
to the tests directory and performs tests of the installed package.

Signed-off-by: David Brown <dmlb2000@gmail.com>

* Fix pre-commit and change the install docs

This moves the install and example documentation to the docs
directory. Also update pre-commit config

Signed-off-by: David Brown <dmlb2000@gmail.com>

Author: dmlb2000

.pre-commit-config.yaml

@@ -1,17 +1,19 @@
 exclude: 'jsonpath2/parser/JSONPath.*'
 repos:
+-   repo: https://github.com/pre-commit/mirrors-autopep8
+    rev: v1.4.4
+    hooks:
+            -   id: autopep8
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    rev: v1.2.3
+    rev: v2.2.3
     hooks:
-            -   id: autopep8-wrapper
             -   id: fix-encoding-pragma
             -   id: trailing-whitespace
             -   id: flake8
                 args: [--max-line-length=120]
             -   id: check-merge-conflict
             -   id: double-quote-string-fixer
             -   id: end-of-file-fixer
-            -   id: name-tests-test
             -   id: debug-statements
             -   id: check-added-large-files
             -   id: check-ast
@@ -48,7 +50,7 @@ repos:
                 language: system
                 types: [python]
 -   repo: git://github.com/Lucas-C/pre-commit-hooks
-    rev: v1.1.5
+    rev: v1.1.6
     hooks:
     -   id: remove-tabs
     -   id: remove-crlf

.travis.yml

@@ -3,12 +3,15 @@ language: python
 stages:
 - lint
 - test
+- test-docs
 - deploy
 
 ".test_script": &1
-- coverage run --include='jsonpath2/*' --omit='jsonpath2/parser/JSONPath*' -m pytest -v
-- coverage report -m --fail-under 100
 - pip install .
+- cd tests
+- coverage run --include='*/site-packages/jsonpath2/*' --omit='*/site-packages/jsonpath2/parser/JSONPath*' -m pytest -xv
+- coverage report -m --fail-under 100
+- cd ..
 - python setup.py bdist_wheel
 - python setup.py sdist
 
@@ -25,6 +28,15 @@ jobs:
     script: *1
   - python: 3.7
     script: *1
+  - stage: test-docs
+    python: 3.7
+    script:
+    - pip install .
+    - cd docs
+    - sphinx-build -T -E -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html
+    - sphinx-build -T -b readthedocssinglehtmllocalmedia -d _build/doctrees-readthedocssinglehtmllocalmedia -D language=en . _build/localmedia
+    - sphinx-build -b latex -D language=en -d _build/doctrees . _build/latex
+    - sphinx-build -T -b epub -d _build/doctrees-epub -D language=en . _build/epub
   - stage: deploy
     python: 3.7
     script: skip

README.md

@@ -1,270 +1,24 @@
 # jsonpath2
 [![Build Status](https://travis-ci.org/pacifica/python-jsonpath2.svg?branch=master)](https://travis-ci.org/pacifica/python-jsonpath2)
 
-This repository contains an implementation of [JSONPath](http://goessner.net/articles/JsonPath/) ([XPath](https://www.w3.org/TR/xpath/all/) for [JSON](https://www.json.org/)) for the Python programming language.
+This repository contains an implementation of
+[JSONPath](http://goessner.net/articles/JsonPath/)
+([XPath](https://www.w3.org/TR/xpath/all/) for
+[JSON](https://www.json.org/)) for the Python programming
+language.
 
-## API
+## Documentation
 
+For installation, configuration and usage documentation please
+refer to the [Read the Docs](https://jsonpath2.readthedocs.io)
+documentation.
 
-### `match` shortcut function
+* [Installation](docs/installation.md) documentation.
+* [Examples](docs/exampleusage.md) documentation.
 
-The `jsonpath2.match` function is a shortcut to match a given JSON data
-structure against a JSONPath string
 
-```python
->>> import jsonpath2
->>> doc = {'hello': 'Hello, world!'}
->>> [x.current_value for x in jsonpath2.match('$.hello', doc)]
-['Hello, world!']
-```
+## Contributions
 
-### `Path` class
-
-The `jsonpath2.path.Path` class represents a JSONPath.
-
-```python
->>> s = '{"hello":"Hello, world!"}'
-'{"hello":"Hello, world!"}'
->>> import json
->>> d = json.loads(s)
-{'hello':'Hello, world!'}
->>> from jsonpath2.path import Path
->>> p = Path.parse_str('$["hello"]')
-<jsonpath2.path.Path object>
->>> [match_data.current_value for match_data in p.match(d)]
-['Hello, world!']
->>> [match_data.node.tojsonpath() for match_data in p.match(d)]
-['$["hello"]']
-```
-
-This class is constructed with respect to the given instance of the `jsonpath2.nodes.root.RootNode` class (viz., the `root_node` property).
-
-#### `parse_str(strdata)` class method
-
-Parse the given string and return a new instance of this class.
-
-#### `parse_file(fileName, encoding='ascii')` class method
-
-Parse the contents of the given file and return a new instance of this class.
-
-#### `match(root_value)` instance method
-
-Match the given JSON data structure against this instance.
-For each match, yield an instance of the `jsonpath2.node.MatchData` class.
-
-#### `__eq__(other)` instance method
-
-Tests if two instances are equal.
-
-#### `__str__()` instance method
-
-Returns the string representation of this instance.
-
-#### `root_node` property
-
-The root node of the abstract syntax tree for this instance.
-
-### `Node` abstract class
-
-The `jsonpath2.node.Node` class represents the abstract syntax tree for a JSONPath.
-
-#### `__eq__(other)` instance method
-
-Tests if two instances are equal.
-
-#### `__jsonpath__()` instance method
-
-Yields the lexer tokens for the string representation of this instance.
-
-#### `match(root_value, current_value)` instance method
-
-Match the given root and current JSON data structures against this instance.
-For each match, yield an instance of the `jsonpath2.node.MatchData` class.
-
-#### `tojsonpath()` instance method
-
-Returns the string representation of this instance.
-
-### `MatchData` class
-
-The `jsonpath2.node.MatchData` class represents the JSON value and context for a JSONPath match.
-
-This class is constructed with respect to a root JSON value, a current JSON value, and an abstract syntax tree node.
-
-#### `__eq__(other)` instance method
-
-Tests if two instances are equal.
-
-#### `root_value` property
-
-The root JSON value.
-
-#### `current_value` property
-
-The current JSON value (i.e., the matching JSON value).
-
-#### `node` property
-
-The abstract syntax tree node.
-
-## Syntax
-
-| XPath | JSONPath | Description |
-| - | - | - |
-| `/` | `$` | the root JSON value |
-| `.` | `@` | the current JSON value |
-| `/` | `.` or `[]` | child operator |
-| `//` | `..` | recursive descent (depth-first search) |
-| `*` | `*` | wildcard (all elements of a JSON array; all values of a JSON object; otherwise none) |
-| `[]` | `[]` | subscript operator |
-| <code>&#124;</code> | `[,]` | union operator (for two or more subscript operators) |
-| n/a | `[start:end:step]` | slice operator (subset of elements of a JSON array) |
-| `[]` | `?()` | filter expression (for use with subscript operator) |
-
-| JSONPath Filter Expression | Description |
-| - | - |
-| `$` or `@` | nested JSONPath (returns `true` if any match exists; otherwise, returns `false`) |
-| `=`, `!=`, `>`, `>=`, `<`, `<=` | binary operator, where left- and right-hand operands are nested JSONPaths or JSON values (returns `true` if any match exists; otherwise, returns `false`) |
-| `and`, `or`, `not` | Boolean operator, where operands are JSONPath filter expressions |
-| `(` ... `)` | parentheses |
-
-## Functions
-
-> See [#14](https://github.com/pacifica/python-jsonpath2/pull/14) for more information.
-
-The syntax for a function call is the name of the function followed by the arguments in parentheses, i.e., `name(arg1, arg2, ..., argN)`, where the arguments are either JSONPaths or JSON values.
-
-```python
->>> s = '{"hello":"Hello, world!"}'
-'{"hello":"Hello, world!"}'
->>> import json
->>> d = json.loads(s)
-{'hello':'Hello, world!'}
->>> from jsonpath2.path import Path
->>> p = Path.parse_str('$["hello"][length()]')
-<jsonpath2.path.Path object>
->>> [m.current_value for m in p.match(d)]
-[13]
->>> [m.node.tojsonpath() for m in p.match(d)]
-['$["hello"][length()]']
-```
-
-| JavaScript Function | Signature |
-| - | - |
-| [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) | `length(): int` |
-| [`Array.prototype.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries) | `entries(): List[Tuple[int, Any]]` |
-| [`Array.prototype.keys()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys) | `keys(): List[int]` |
-| [`Array.prototype.values()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values) | `values(): List[Any]` |
-| [`Object.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries) | `entries(): List[Tuple[str, Any]]` |
-| [`Object.keys()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys) | `keys(): List[str]` |
-| [`Object.values()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values) | `values(): List[Any]` |
-| [`string.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) | `length(): int` |
-| [`String.prototype.charAt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt) | `charAt(index: int): str` |
-| [`String.prototype.substring()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) | `substring(indexStart: int, indexEnd: Optional[int]): str` |
-
-<!-- | `Array.prototype.concat()` | |
-| `Array.prototype.fill()` | |
-| `Array.prototype.flat()` | |
-| `Array.prototype.includes()` | |
-| `Array.prototype.indexOf()` | |
-| `Array.prototype.join()` | |
-| `Array.prototype.lastIndexOf()` | |
-| `Array.prototype.slice()` | |
-| `Array.prototype.sort()` | |
-| `Array.prototype.splice()` | |
-| `JSON.parse()` | |
-| `JSON.stringify()` | |
-| `Math.abs()` | |
-| `Math.acos()` | |
-| `Math.acosh()` | |
-| `Math.asin()` | |
-| `Math.asinh()` | |
-| `Math.atan()` | |
-| `Math.atan2()` | |
-| `Math.atanh()` | |
-| `Math.cbrt()` | |
-| `Math.ceil()` | |
-| `Math.clz32()` | |
-| `Math.cos()` | |
-| `Math.cosh()` | |
-| `Math.exp()` | |
-| `Math.expm1()` | |
-| `Math.floor()` | |
-| `Math.fround()` | |
-| `Math.hypot()` | |
-| `Math.imul()` | |
-| `Math.log()` | |
-| `Math.log10()` | |
-| `Math.log1p()` | |
-| `Math.log2()` | |
-| `Math.max()` | |
-| `Math.min()` | |
-| `Math.pow()` | |
-| `Math.random()` | |
-| `Math.round()` | |
-| `Math.sign()` | |
-| `Math.sin()` | |
-| `Math.sinh()` | |
-| `Math.sqrt()` | |
-| `Math.tan()` | |
-| `Math.tanh()` | |
-| `Math.trunc()` | |
-| `Number.isFinite()` | |
-| `Number.isInteger()` | |
-| `Number.isNaN()` | |
-| `Number.isSafeInteger()` | |
-| `Number.parseFloat()` | |
-| `Number.parseInt()` | |
-| `String.prototype.codeCharAt()` | |
-| `String.prototype.codePointAt()` | |
-| `String.prototype.concat()` | |
-| `String.prototype.endsWith()` | |
-| `String.prototype.includes()` | |
-| `String.prototype.indexOf()` | |
-| `String.prototype.lastIndexOf()` | |
-| `String.prototype.localeCompare()` | |
-| `String.prototype.match()` | |
-| `String.prototype.normalize()` | |
-| `String.prototype.padEnd()` | |
-| `String.prototype.padStart()` | |
-| `String.prototype.repeat()` | |
-| `String.prototype.replace()` | |
-| `String.prototype.search()` | |
-| `String.prototype.slice()` | |
-| `String.prototype.split()` | |
-| `String.prototype.startsWith()` | |
-| `String.prototype.toLocaleLowerCase()` | |
-| `String.prototype.toLocaleUpperCase()` | |
-| `String.prototype.toLowerCase()` | |
-| `String.prototype.toUpperCase()` | |
-| `String.prototype.trim()` | |
-| `String.prototype.trimEnd()` | |
-| `String.prototype.trimStart()` | | -->
-
-In the above table, the type aliases (`Any`, `List`, `Optional` and `Tuple`) are defined by the [`typing`](https://docs.python.org/3/library/typing.html) module from the Python Standard Library.
-
-## Grammar and parser
-
-The [ANTLR v4](https://github.com/antlr/antlr4) grammar for JSONPath is available at `jsonpath2/parser/JSONPath.g4`.
-
-### Installing ANTLR v4
-
-Adapted from https://github.com/antlr/antlr4/blob/master/doc/getting-started.md.
-
-```bash
-cd /usr/local/lib
-curl -O http://www.antlr.org/download/antlr-4.7.1-complete.jar
-
-export CLASSPATH=".:/usr/local/lib/antlr-4.7.1-complete.jar:$CLASSPATH"
-
-alias antlr4='java -Xmx500M -cp "/usr/local/lib/antlr-4.7.1-complete.jar:$CLASSPATH" org.antlr.v4.Tool'
-alias grun='java org.antlr.v4.gui.TestRig'
-```
-
-### Building the parser for the grammar
-
-Adapted from https://github.com/antlr/antlr4/blob/master/doc/python-target.md.
-
-```bash
-antlr4 -Dlanguage=Python3 -o . -lib . jsonpath2/parser/JSONPath.g4
-```
+Contributions are accepted on GitHub via the fork and pull request workflow.
+GitHub has a good [help article](https://help.github.com/articles/using-pull-requests/)
+if you are unfamiliar with this method of contributing.

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+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)