From b296fb0207f6ef1a0066aec73c5ee6c460b419ee Mon Sep 17 00:00:00 2001 From: Brett Smith Date: Wed, 20 May 2020 10:52:08 -0400 Subject: [PATCH] accrual: Add docstring with program overview. --- conservancy_beancount/reports/accrual.py | 45 +++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/conservancy_beancount/reports/accrual.py b/conservancy_beancount/reports/accrual.py index 5438383..175f781 100644 --- a/conservancy_beancount/reports/accrual.py +++ b/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