docs: Better usage docs

docs/index.rst

@@ -2,6 +2,19 @@
 Welcome to pyastgrep's documentation!
 =====================================
 
+pyastgrep is a command-line utility (and library) for grepping Python files
+using XPath syntax (or CSS selectors) against the Python AST (Abstract Syntax
+Tree).
+
+In other words, this allows you to search Python code against specific syntax
+elements (function definitions, arguments, assignments, variables etc), instead
+of grepping for string matches.
+
+The interface and behaviour is designed to match grep and ripgrep as far as it
+makes sense to do so.
+
+The project is hosted on `Github <https://github.com/spookylukey/pyastgrep/>`_.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/usage.rst

@@ -10,8 +10,16 @@ You can omit files or directories and the current directory (and
 sub-directories) will be searched. It’s designed to be used like `ripgrep
 <https://github.com/BurntSushi/ripgrep/>`_.
 
-See ``pyastgrep --help`` for more command line options.
+The above command does the following:
 
+- it search the files or directories specified for Python files
+- it parses the Python source to AST, and converts this to XML using a very
+  simple one-to-one mapping from AST nodes to XML nodes.
+- it searches the XML documents for nodes that match the given XPath expression
+- it prints the Python code for the matching nodes
+
+See ``pyastgrep --help`` for more command line options, which include the
+ability to use CSS selectors instead of XPath expressions, and other options.
 
 pyastgrep in action
 ===================