Update documentation

.gitignore

@@ -1,2 +1,3 @@
 __pycache__
 /config.yml
+/venv

README.md

@@ -0,0 +1,47 @@
+# ledger-pyreport
+
+ledger-pyreport is a lightweight Flask webapp for generating interactive and printable accounting reports from [ledger-cli](https://www.ledger-cli.org/) data.
+
+## Reports
+
+* Trial balance, and comparative trial balance
+* Balance sheet, and comparative balance sheet
+* Income statement, and comparative income statement
+* General ledger
+* Account transactions, with or without itemisation of commodities
+* Transaction detail, with or without itemisation of commodities
+
+## Features
+
+* Correctly values assets/liabilities at market value, and income/expenses at cost (pursuant to [AASB 121](https://www.aasb.gov.au/admin/file/content105/c9/AASB121_08-15_COMPfeb16_01-19.pdf)/[IAS 21](https://www.ifrs.org/issued-standards/list-of-standards/ias-21-the-effects-of-changes-in-foreign-exchange-rates/) para 39)
+* Correctly computes unrealised gains ([even when Ledger does not](https://yingtongli.me/blog/2020/03/31/ledger-gains.html))
+* Simulates annual closing of books, with presentation of income/expenses on the balance sheet as retained earnings and current year earnings
+* Can simulate cash basis accounting, using FIFO methodology to recode transactions involving liabilities and non-cash assets
+
+## Background, demo and screenshots
+
+See [https://yingtongli.me/blog/2020/03/31/ledger-pyreport.html](https://yingtongli.me/blog/2020/03/31/ledger-pyreport.html) for further discussion.
+
+## Usage
+
+Install the dependencies from PyPI, optionally in a virtual environment: (Commands presented for Linux/Mac)
+
+```
+virtualenv venv
+. venv/bin/activate
+pip install -r requirements.txt
+```
+
+Copy *config.example.yml* to *config.yml* (or set the *LEDGER_PYREPORT_CONFIG* environment variable to the path to the config file).
+
+Run as per a usual Flask app, for example:
+
+```
+FLASK_APP=ledger_pyreport python -m flask run
+```
+
+## Notes on Ledger setup
+
+ledger-pyreport expects each of assets, liabilities, equity, income and expenses to be setup in Ledger as a separate top-level account. These accounts should contain a zero balance, with all transactions in child accounts.
+
+Additionally, ledger-pyreport expects the next level of assets and liabilities to be categories of asset and liability (e.g. *Assets:Current*, *Liabilities:Non-current*). These, too, should contain a zero balance.

config.example.yml

@@ -16,6 +16,6 @@ retained_earnings: 'Equity:Retained Earnings'
 current_year_earnings: 'Equity:Current Year Earnings'
 
 # Which asset accounts to consider in cash basis mode
-cash_asset_accounts: ['Assets:Cash on Hand', 'Assets:Cash at Bank']
+cash_asset_accounts: ['Assets:Current:Cash on Hand', 'Assets:Current:Cash at Bank']
 # Which account to charge non-cash transactions to in cash basis mode, when no other account is suitable
 cash_other_income: 'Income:Other Income'

demo/config.yml

@@ -0,0 +1,21 @@
+# Set up how we will call Ledger
+ledger_file: demo/ledger.journal
+ledger_args: []
+report_currency: ['$', True] # True if prefix, False if suffix
+
+# Tell ledger-pyreport about the top-level account categories
+assets_account: Assets
+liabilities_account: Liabilities
+equity_account: Equity
+income_account: Income
+expenses_account: Expenses
+
+# These accounts will automatically be populated on reports
+unrealized_gains: 'Equity:Unrealized Gains'
+retained_earnings: 'Equity:Retained Earnings'
+current_year_earnings: 'Equity:Current Year Earnings'
+
+# Which asset accounts to consider in cash basis mode
+cash_asset_accounts: ['Assets:Current:Cash on Hand', 'Assets:Current:Cash at Bank', 'Assets:Current:International Account']
+# Which account to charge non-cash transactions to in cash basis mode, when no other account is suitable
+cash_other_income: 'Income:Other Income'

demo/ledger.journal

@@ -0,0 +1,36 @@
+2019-06-30 Conversion balances
+    Assets:Current:Cash at Bank             $1000.00
+    Assets:Current:Cash on Hand               $50.00
+    Assets:Non-current:Plant                $5000.00
+    Equity:Retained Earnings
+
+2019-07-01 Loan
+    Assets:Current:Cash at Bank              $500.00
+    Liabilities:Non-current:Personal Loan
+
+2019-07-02 Application
+    Assets:Current:International Account      100.00 EUR @ $1.10
+    Assets:Current:Cash at Bank
+
+2019-08-01 Interest on personal loan
+    Expenses:Interest                        $100.00
+    Liabilities:Non-current:Personal Loan
+
+2019-08-02 Application
+    Assets:Current:International Account      100.00 EUR @ $1.05
+    Assets:Current:Cash at Bank
+
+2019-09-01 Paycheck
+    Assets:Current:Cash at Bank              $200.00
+    Income:Wages
+
+2019-09-02 Redemption
+    Assets:Current:Cash at Bank               $57.50
+    Assets:Current:International Account      -50.00 EUR {$1.10} @ $1.15
+    Income:Capital Gains
+
+2019-10-01 Depreciation
+    Expenses:Depreciation                    $500.00
+    Assets:Non-current:Plant:Less Accumulated Depreciation
+
+P 2019-10-01 00:00:00 EUR $1.30

requirements.txt

@@ -0,0 +1,7 @@
+click==7.1.1
+Flask==1.1.1
+itsdangerous==1.1.0
+Jinja2==2.11.1
+MarkupSafe==1.1.1
+PyYAML==5.3.1
+Werkzeug==1.0.0