query: Add overview docstring.

conservancy_beancount/reports/query.py

@@ -1,4 +1,44 @@
-"""query.py - Report arbitrary queries with advanced loading and formatting"""
+"""query.py - Report arbitrary queries with advanced loading and formatting
+
+This tool extends Beancount's bean-query with the following:
+
+* ``META_DOCS("meta-key")`` function: Given the name of metadata with
+  documentation in it, returns a list of the documentation links.
+
+* ``STR_META("meta-key")`` function: Looks up metadata like ANY_META, then
+  returns the result as a nicely formatted string, to make sorting easier or
+  just provide prettier reports.
+
+* ``SET()`` function: Returns only unique arguments over a GROUP BY.
+
+* ODS output format, with proper formatting of currency and documentation links.
+
+* Loads books from your configuration file, with options available to specify
+  which year(s) to load.
+
+* Can load rewrite rules just like other reports. Your queries will show the
+  transformed entries.
+
+* Improved error reporting.
+
+Run it like bean-query, except instead of specifying a books filename, use
+date options like ``--begin``, ``--end``, ``--fy``, and ``--cy`` to specify
+the year(s) you want to load. Run ``query-report --help`` for details about
+those.
+
+Start an interactive shell::
+
+    query-report [year options]
+
+Write a spreadsheet with results for one query::
+
+    query-report [year options] [-O OUTPUT.ods] <query string>
+
+    query-report [year options] [-O OUTPUT.ods] < QUERY_FILE.bql
+
+query-report also accepts all the same options as bean-query, like ``--format``
+and ``--numberify``.
+"""
 # Copyright © 2021  Brett Smith
 # License: AGPLv3-or-later WITH Beancount-Plugin-Additional-Permission-1.0
 #