#67, #68 logo and more docs changes

README.md

@@ -7,9 +7,9 @@ A minimal, yet valid double-entry accounting system in Python.
 
 ## Documentation
 
-...
+See project documentation at <https://epogrebnyak.github.io/abacus/>.
 
-## Install
+## Installation
 
 ```
 pip install abacus-py
@@ -23,18 +23,18 @@ pip install git+https://github.com/epogrebnyak/abacus.git
 
 `abacus-py` requires Python 3.10 or higher.
 
-## Command line tools
+## Command line tool
 
 There are two command line tools available after you install this package: `abacus` and `cx`.
 You can check them as:
 
 ```bash
 abacus --help
-cx --help
+buh --help
 ```
 
 `abacus` has a full set of commands and options, while `cx` is just several commands with a more simple syntax.
-`cx` is ideal for solving textbook exercises.
+
 Both tools enable to complete a full accounting cycle and share the same data model.
 They create and modify two files `chart.json` and `entries.linejson` in your project folder.
 

abacus/core.py

@@ -1,4 +1,4 @@
-"""A minimal, yet valid double-entry accounting system.
+"""Core elements of a minimal double-entry accounting system.
 
 Using this module you can:
 
@@ -20,7 +20,8 @@
 2. account names must be globally unique,
 3. no cashflow statement yet,
 4. one currency,
-5. no checks for account non-negativity.
+5. no checks for account non-negativity,
+6. simple entry format, just debit and credit account names and transaction amount. 
 """
 import json
 from abc import ABC, abstractmethod

docs/chart_of_accounts.md → docs/accounting/chart_of_accounts.md

@@ -1,15 +1,16 @@
 # Chart of accounts
 
 Chart of accounts (CAO) is a list of accounts to be used by a company.
-Chart of accounts may be defined by the government (in Europe)
-or can be specified by the company itself according to guidelines (in the US).
+Chart of accounts may be defined by the government (as in Europe)
+or can be specified by the company itself according to guidelines (as in the US).
 Fiscal rules and reporting requirements also affect composition of a chart of accounts.
 
-Charts of accounts are not that easy to find in an open, structured and machine-readable format.
+Charts of accounts are not that easy to find in an open,
+structured and machine-readable format.
 They usually exist as a published PDF document (sometimes an Excel file)
 or may be deeply embedded in accounting software, either open source (like Odoo)
 or proprietary (Oracle, SAP, NetSuite, Xero or QuickBooks).
-[Odoo][odoo] is specific has a list of localisations for many countries.
+[Odoo][odoo] in specific has a list of localisations for many countries.
 
 [odoo]: https://www.odoo.com/documentation/16.0/applications/finance/fiscal_localizations.html
 
@@ -27,6 +28,3 @@ There are also textbook charts and sample charts like [Dunder Muffin Paper Compa
 
 `abacus` allows to create and maintain charts of accounts as JSON files.
 After a chart is specified, one can post entries and create financial reports.
-Migration between domestic and IFRS-compatible charts considered for `abacus`, but not implemented yet (see [issue #4][4]).
-
-[4]: https://github.com/epogrebnyak/abacus/issues/4

docs/accounting/introduction.md

@@ -0,0 +1,76 @@
+# Introduction to accounting
+
+The `abacus` user is expected to have some task in mind that is solvable using Python code or scripts. But if you are totally new to the accounting area subject? Here is an introductory guide accounting, broken into several steps.
+
+## Limited liability concept
+
+1. A firm is an entity that is legally separate from shareholders. The shareholders risk  
+   loosing their investment into the firm if things turn bad, but are not liable for any losses beyond that amount that may arise from firm operations.
+
+2. The shareholders, creditors, trading partners and other parties want to know if
+   the firm is profitable and if it can meet obligations to repay its debt. For that
+   reason the firm discloses financial information.
+
+## Balance sheet and income statement view of the firm
+
+1. A firm keeps records of the resources that the firm owns (assets) and sources of funds -- shareholder equity (or capital) and liabilities (debt). This is a firm financial position, or balance sheet view of the firm.
+
+2. A firm also keeps records of income and expenses that indicate does the firm make a profit or run a loss. This is income statement view of the firm.
+
+3. Balance sheet and income statement are derived from the same data linked together in an accounting equation as explained below.
+
+## Assets, capital, liabilities
+
+3. Capital and liabilities indicate who has claims on the firm. A claim shows where the money came from and where the money should be distributed if the firm is liquidated. Claims also have order of precedence – which claims are fulfilled first in a liquidation.
+
+4. Capital, or equity, are funds provided by firm owners. The shareholders expect the firm will make a profit by allocating these funds at the best of their interest and distribute all or part of this profit back to shareholders as dividend. The profit not distributed remains with the firm as 'retained earnings'.
+
+5. Liabilities are financial obligations of the firm. These are the records of what the firm owes to other parties. When a firm takes a loan for a bank it is reflected as a liability. Also when some payment is due but not yet fulfilled this amount is also reflected as a firm's liability (for example, interest payment on a loan that is die. but was not mede yet). Liabilities are classified based on duration as current liabilities (due within a year) and long term liabilities (due at time beyond one year).
+
+6. Assets is everything that is owned by the firm itself and what can be converted into cash. Assets are classified into fixed, or non-current, assets (like property, plant, and equipment) and current assets (like cash and inventory).
+
+## Assets = Capital + Liabilities
+
+7. An accounting identity `Assets = Equity + Liabilities` is a statement that says the sources of funds are equal to the uses of funds. This is a published form of balance sheet statement at the end of an accounting period (a quarter or a year). In this representation the current period profit was already distributed to dividend and retained earnings and does not appear on a balance sheet as separate entity.
+
+8. Profit of the firm is revenue (or sales, or income) less expenses associated with this revenue: `Profit = Income - Expenses`. The report containing this data is income statement.
+
+9. In accounting equation profit is recorded on the right side where capital and liabilities side. Why so? Profit is an increment of capital invested into the firm, so it appears next to equity. When no dividends are paid, all of the current profit will add up to retained earnings, which is a component of equity. When the firm incurs a loss, this loss will diminish the firm capital.
+
+## Extended accounting identity
+
+10. Within a reporting period, the accounting equation can be written as `Assets = Equity + Profit + Liabilities`, where `Profit` is the current period profit before dividend. Substituting `Profit = Income - Expenses` into the equation and rearranging we get the extended form of the accounting identity:
+
+```
+Assets + Expenses = Equity + Liabilities + Income
+```
+
+9. The extended accounting equation always holds true. Whenever a new accounting transaction is recorded you are just changing some variables in this equation. In a double entry, you change two variables, in a compound entry you change several variables. If you try to record just one change, for example, just receipt of cash from a customer as increase in `Assets`, the equation will break. For cash receipt from customer, you should record an increase in `Income` and an equal increase in `Assets`.
+
+## Recording transactions
+
+10. You may take a mind experiment and thinking of various business transactions and provide examples of four types of double entries:
+
+- two variables of the right side are changed;
+- two variables of the left side are changed;
+- both left side and right side are increased;
+- both right side and left side are decreased.
+
+11. You do not specifically need debits and credits to manipulate the extended accounting equation. The debits and credits are just a convenient notation system that helps denote which accounts are increased and which decreased. Understanding the extended accounting equation if far more important and probably should come before learning the debit and credit system. In traditional teaching this is other way around.
+
+## Is real accounting system different from above?
+
+12. A "real" accounting system would have more components, like keeping track
+    of original paperwork or electronic documents that validate the information 
+    that enters the system.
+
+13. On account system side there may be "contra" accounts added that keep track 
+    of changes in original accounts, for example "depreciation" contra account 
+    for "property, plant, equipment" or "refunds" contra account for "sales". 
+
+14. On recognition, valuation and reporting sides important aspects are:
+
+   - accrual basis and recording of receivables and payables;
+   - fair value, depreciation and amortization concepts, valuation changes;
+   - deferred or accrued income and expenses and adjustment entries.
+

docs/index.md

@@ -1,120 +1,11 @@
-# A minimal, yet valid double-entry accounting system in Python
+<img width="64" align="right" src="assets/robot.png">
 
-`abacus` is an experimental package that aims to show that
-accounting can be done with simple code.
+# Minimal, yet valid double-entry accounting system in Python
 
-With `abacus` you can perform complete accounting cycle,
-including the following:
+`abacus` is an Python package and a command line tool that
+makes accounting calculations with code simple.
 
-- define a chart of accounts,
-- post entries to ledger,
-- make trial balance and adjustment entries,
-- close accounts at period end,
-- produce balance sheet and income statement,
-- carry account balances forward to the next period.
+With `abacus` you can perform a complete accounting cycle
+from defining own chart of account to making financial reports.
 
-Currently, `abacus` exists as a Python package and a command line tool.
-This means you can write you own Python code or short scripts
-that would perform accounting operations.
-
-`abacus` is particularly well suited for solving textbook examples,
-that involve deciding on which accounting entries reflect business events.
-There is a collection of textbook examples on this site. 
-
-The big goal for `abacus` is to become a DSL (domain-specific language)
-for accounting, in other words, a notation system that
-allows to formulate accounting operations and demonstrate their results.
-This system would be independent of a specific provider. 
-
-## Minimal example
-
-A firm starts business with a $5000 shareholder investment,
-spends $1000 on marketing,
-earns $3499 from clients,
-and pays $2000 in salaries.
-
-The Python code below will produce the balance sheet and income statement for the firm.
-
-```python
-from abacus import Chart, Report, echo
-
-# Create a chart of accounts
-chart = Chart(
-    assets=["cash"],
-    capital=["equity"],
-    income=["services"],
-    expenses=["marketing", "salaries"],
-)
-
-# Create a ledger using the chart
-ledger = chart.ledger()
-
-# Post entries to ledger
-ledger.post(debit="cash", credit="equity", amount=5000)
-ledger.post(debit="marketing", credit="cash", amount=1000)
-ledger.post(debit="cash", credit="services", amount=3499)
-ledger.post(debit="salaries", credit="cash", amount=2000)
-
-# Print trial balance, balance sheet and income statement
-report = Report(chart, ledger)
-echo(report.trial_balance, "Trial balance")
-echo(report.balance_sheet, "Balance sheet")
-echo(report.income_statement, "Income statement")
-print("Account balances:", report.account_balances)
-```
-
-This code can be found at [readme.py](readme.py).
-
-<details>
-    <summary>See the program output
-    </summary>
-
-```
-(base) Q:\abacus>poetry run python readme.py
-
-Trial balance
-   Account    Debit  Credit
-cash ........   5499      0
-marketing ...   1000      0
-salaries ....   2000      0
-equity ......      0   5000
-re ..........      0      0
-services ....      0   3499
-isa .........      0      0
-null ........      0      0
-
-Balance sheet
-ASSETS... 5499  CAPITAL....... 5499
-  Cash... 5499    Equity...... 5000
-.........         Re..........  499
-.........       LIABILITIES...    0
-TOTAL:... 5499  TOTAL:........ 5499
-
-Income statement
-INCOME........... 3499
-  Services....... 3499
-EXPENSES:........ 3000
-  Marketing...... 1000
-  Salaries....... 2000
-CURRENT PROFIT...  499
-
-Account balances: {'cash': 5499, 'equity': 5000, 're': 0, 'services': 3499, 'marketing': 1000, 'salaries': 2000, 'isa': 0, 'null': 0}
-```
-
-</details>
-
-## Accounting cycle
-
-`abacus` enables to complete an accounting cycle in following steps.
-
-1. Define a chart of accounts with five types of accounts (assets, expenses, capital, liabilities and income) and contra accounts (eg depreciation).
-2. Create a blank general ledger for a new company or a general ledger with starting balances from previous period for existing company.
-3. Post entries to a general ledger individually or in bulk.
-4. View trial balance.
-5. Make adjustment entries.
-6. Close income and expenses accounts and transfer current period profit (loss) to retained earnings.
-7. Make post-close entries (eg accrue dividend due to shareholders upon dividend announcement).
-8. View and save income statement and balance sheet reports.
-9. Save period end account balances and use them to initialize a general ledger at the start of a next accounting period.
-
-More usage ideas in [Motivation](#motivation) section below.
+To start using `abacus`, install it and go to Quick Start section.

docs/install.md

@@ -0,0 +1,21 @@
+# How to install
+
+`abacus` requires Python 3.10 or higher.
+
+To install:
+
+```
+pip install abacus-py
+```
+
+For latest version install from github:
+
+```
+pip install git+https://github.com/epogrebnyak/abacus.git
+```
+
+Type in command line to try new installation:
+
+```
+abacus --help
+```

docs/motivation.md

@@ -0,0 +1,26 @@
+# Motivation
+
+## Original intent
+
+`abacus` started as a project to demonstrate principles of double-entry accounting
+through Python code, in spirit of [build-your-own-x](https://github.com/codecrafters-io/build-your-own-x).
+
+## Teaching
+
+You can use `abacus` to teach basics of accounting and accounting information systems (AIS),
+or as a project in your Python class.
+
+### Other uses
+
+- Use `abacus` as a software component with other open source tools such as `medici` ledger.
+- Convert reports between charts of accounts, for example local accounting standards to IFRS.
+- Process business events in scenario simulations and make financial reports.
+- Generate prompts for a large language model in accounting (RAG).
+
+## DSL
+
+The big goal for `abacus` is to become a DSL (domain-specific language)
+for accounting, a notation system that allows to formulate accounting operations
+in _'debit this — credit that'_ style and to demonstrate the results
+of these operations as trail balance or financial statements.
+This system would be independent of a specific ERP or book-keeping software vendor.

docs/quick_start.md

@@ -0,0 +1,12 @@
+# Quick start
+
+With `abacus` you can do the following parts of accounting work:
+
+1. define a chart of accounts,
+2. post entries to ledger,
+3. make trial balance and adjustment entries,
+4. close accounts at period end,
+5. make balance sheet and income statement.
+
+There is no cashflow statement yet, other simplifications also
+apply (one currency, unique account identifiers).