accrual: Add docstring with program overview.

conservancy_beancount/reports/accrual.py

@@ -1,5 +1,48 @@
 #!/usr/bin/env python3
-"""accrual.py - Various reports about accruals"""
+"""accrual-report - Status reports for accruals
+
+accrual-report checks accruals (postings under Assets:Receivable and
+Liabilities:Payable) for errors and metadata consistency, and reports any
+problems on stderr. Then it writes a report about the status of those
+accruals on stdout.
+
+The typical way to run it is to pass an RT ticket number or invoice link as an
+argument::
+
+    # Report all accruals associated with RT#1230:
+    accrual-report 1230
+    # Report all accruals with the invoice link rt:45/670.
+    accrual-report 45/670
+    # Report all accruals with the invoice link Invoice980.pdf.
+    accrual-report Invoice980.pdf
+
+By default, to stay fast, accrual-report only looks for postings from the
+beginning of the last fiscal year. You can search further back in history
+by passing the ``--since`` argument. The argument can be a fiscal year, or
+a negative number of how many years back to search::
+
+    # Search for accruals since 2016
+    accrual-report --since 2016 [search terms …]
+    # Search for accruals from the beginning of three fiscal years ago
+    accrual-report --since -3 [search terms …]
+
+If you want to further limit what accruals are reported, you can match on
+other metadata by passing additional arguments in ``name=value`` format.
+You can pass any number of search terms. For example::
+
+    # Report accruals associated with RT#1230 and Jane Doe
+    accrual-report 1230 entity=Doe-Jane
+
+accrual-report will automatically decide what kind of report to generate from
+the results of your search. If the search matches a single outstanding payable,
+it will write an outgoing approval report; otherwise, it writes a basic balance
+report. You can request a specific report type with the ``--report-type``
+option::
+
+    # Write an outgoing approval report for all outstanding accruals for
+    # Jane Doe, even if there's more than one
+    accrual-report --report-type outgoing entity=Doe-Jane
+"""
 # Copyright © 2020  Brett Smith
 #
 # This program is free software: you can redistribute it and/or modify