docs: stubs and high level api reference

Author: jg-rp

.gitignore

@@ -51,8 +51,9 @@ cov.xml
 *.mo
 *.pot
 
-# Sphinx documentation
+# Documentation
 docs/_build/
+site/
 
 # PyBuilder
 target/

CHANGELOG.md

@@ -6,7 +6,7 @@
 
 - Added support for function extensions.
 - Added the built-in `length()` function.
-- Added the built-in `count()` function. `count()` is an alias for `length()`
+- Added the built-in `count()` function. `count()` is an alias for `length()`.
 - Support filters without parentheses.
 - Adhere to IETF JSONPath draft escaping in quoted property selectors.
 - Handle UTF-16 surrogate pairs in quoted property selectors.

docs/advanced.md

@@ -0,0 +1,3 @@
+# Advanced
+
+TODO

docs/api.md

@@ -0,0 +1,13 @@
+# API Reference
+
+::: jsonpath.JSONPathEnvironment
+    handler: python
+
+::: jsonpath.JSONPathMatch
+    handler: python
+
+::: jsonpath.JSONPath
+    handler: python
+
+::: jsonpath.CompoundJSONPath
+    handler: python

docs/async.md

@@ -0,0 +1,3 @@
+# Async
+
+TODO

docs/css/style.css

@@ -0,0 +1,27 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: .05rem solid var(--md-typeset-table-color);
+  }
+  
+  /* Mark external links as such. */
+  a.autorefs-external::after {
+    /* https://primer.style/octicons/arrow-up-right-24 */
+    background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+    content: ' ';
+  
+    display: inline-block;
+    position: relative;
+    top: 0.1em;
+    margin-left: 0.2em;
+    margin-right: 0.1em;
+  
+    height: 1em;
+    width: 1em;
+    border-radius: 100%;
+    background-color: var(--md-typeset-a-color);
+  }
+  a.autorefs-external:hover::after {
+    background-color: var(--md-accent-fg-color);
+  }
+  

docs/custom_api.md

@@ -0,0 +1,3 @@
+# Low Level API Reference
+
+TODO

docs/exceptions.md

@@ -0,0 +1,3 @@
+# Exceptions
+
+::: jsonpath.JSONPathError

docs/index.md

@@ -0,0 +1,106 @@
+# Python JSONPath
+
+JSONPath is a mini language for selecting objects from data formatted in JavaScript Object Notation, or equivalent Python objects, like dictionaries and lists.
+
+## Install
+
+Install Python JSONPath using [pip](https://pip.pypa.io/en/stable/getting-started/):
+
+```console
+pip install python-jsonpath
+```
+
+Or [Pipenv](https://pipenv.pypa.io/en/latest/):
+
+```console
+pipenv install python-jsonpath
+```
+
+## Example
+
+```python
+import jsonpath
+
+example_data = {
+    "categories": [
+        {
+            "name": "footwear",
+            "products": [
+                {
+                    "title": "Trainers",
+                    "description": "Fashionable trainers.",
+                    "price": 89.99,
+                },
+                {
+                    "title": "Barefoot Trainers",
+                    "description": "Running trainers.",
+                    "price": 130.00,
+                },
+            ],
+        },
+        {
+            "name": "headwear",
+            "products": [
+                {
+                    "title": "Cap",
+                    "description": "Baseball cap",
+                    "price": 15.00,
+                },
+                {
+                    "title": "Beanie",
+                    "description": "Winter running hat.",
+                    "price": 9.00,
+                },
+            ],
+        },
+    ],
+    "price_cap": 10,
+}
+
+products = jsonpath.findall("$..products.*", example_data)
+print(products)
+```
+
+Which results in a list of all products from all categories:
+
+```json
+[
+  {
+    "title": "Trainers",
+    "description": "Fashionable trainers.",
+    "price": 89.99
+  },
+  {
+    "title": "Barefoot Trainers",
+    "description": "Running trainers.",
+    "price": 130.0
+  },
+  {
+    "title": "Cap",
+    "description": "Baseball cap",
+    "price": 15.0
+  },
+  {
+    "title": "Beanie",
+    "description": "Winter running hat.",
+    "price": 9.0
+  }
+]
+```
+
+Or, reading data from a JSON formatted file:
+
+```python
+import jsonpath
+
+with open("some.json") as fd:
+    products = jsonpath.findall("$..products.*", fd)
+
+print(products)
+```
+
+## Next Steps
+
+Have a read through the [Quick Start](quickstart.md) and [High Level API Reference](api.md).
+
+If you're interested in customizing JSONPath, take a look at [Advanced Usage](advanced.md) and the [Low Level API Reference](custom_api.md).

docs/quickstart.md

@@ -0,0 +1,3 @@
+# Quick start
+
+TODO