Documentation tweaks

docs/getting_started/filtering.md

@@ -5,6 +5,8 @@ This guide will briefly outline how to parse OPTIMADE filter strings into databa
 
 ## Parsing OPTIMADE filter strings
 
+The [`LarkParser`][optimade.filterparser.LarkParser] class will take an OPTIMADE filter string, supplied by the user, and parse it into a `lark.Tree` instance.
+
 Example use:
 
 ```python
@@ -66,8 +68,8 @@ filter
 
 ## Flow for parsing a user-supplied filter and converting to a backend query
 
-`optimade.filterparser.LarkParser` will take user input to generate a `lark.Tree` and feed that to a `lark.Transformer`.
-For example, `optimade.filtertransformers.mongo.MongoTransformer` will turn the tree into something useful for a MongoDB backend:
+After the [`LarkParser`][optimade.filterparser.LarkParser] has turned the filter string into a `lark.Tree`, it is fed to a `lark.Transformer` instance, which transforms the 'lark.Tree' into a backend-specific representation of the query.
+For example, [`MongoTransformer`][optimade.filtertransformers.mongo.MongoTransformer] will turn the tree into something useful for a MongoDB backend:
 
 ```python
 # Example: Converting to MongoDB Query Syntax
@@ -94,7 +96,7 @@ print(query)
 
 In order to support a new backend, you will need to create a new filter transformer that inherits from the [`BaseTransformer`][optimade.filtertransformers.base_transformer.BaseTransformer].
 This transformer will need to override the methods that match the particular grammatical constructs in the Lark grammar in order to construct a query.
-Two examples can be found for MongoDB ([`MongoTransformer`][optimade.filtertransformers.mongo.MongoTransformer]) and Elasticsearch ([`ElasticTransformer`][optimade.filtertransformers.elasticsearch.ElasticTransformer]).
+Two examples can be found within `optimade-python-tools`, one for MongoDB ([`MongoTransformer`][optimade.filtertransformers.mongo.MongoTransformer]) and one for Elasticsearch ([`ElasticTransformer`][optimade.filtertransformers.elasticsearch.ElasticTransformer]).
 
 In some cases, you may also need to extend the base [`EntryCollection`][optimade.server.entry_collections.entry_collections.EntryCollection], the class that receives the transformed filter as an argument to its private `._run_db_query()` method.
 This class handles the connections to the underlying database, formatting of the response in an OPTIMADE format, and other API features such as sorting and pagination.

docs/getting_started/validation.md

@@ -44,11 +44,12 @@ positional arguments:
   base_url              The base URL of the OPTIMADE
                         implementation to point at, e.g.
                         'http://example.com/optimade/v1' or
-                        'http://localhost:5000/v1
+                        'http://localhost:5000/v1'
 
 optional arguments:
   -h, --help            show this help message and exit
   -v, --verbosity       Increase the verbosity of the output.
+                        (-v: warning, -vv: info, -vvv: debug)
   -j, --json            Only a JSON summary of the validator
                         results will be printed to stdout.
   -t AS_TYPE, --as-type AS_TYPE

optimade/validator/__init__.py

@@ -36,15 +36,15 @@ def validate():  # pragma: no cover
         default="http://localhost:5000/v0",
         help=(
             "The base URL of the OPTIMADE implementation to point at, "
-            "e.g. 'http://example.com/optimade/v1' or 'http://localhost:5000/v1"
+            "e.g. 'http://example.com/optimade/v1' or 'http://localhost:5000/v1'"
         ),
     )
     parser.add_argument(
         "-v",
         "--verbosity",
         action="count",
         default=0,
-        help="""Increase the verbosity of the output.""",
+        help="Increase the verbosity of the output. (-v: warning, -vv: info, -vvv: debug)",
     )
     parser.add_argument(
         "-j",