Move all documentation to docs_src, build documentation pages

docs_src/00_Features.md

@@ -0,0 +1,33 @@
+## Features
+
+- Easily editable and processable file format based on [YAML]
+- Modeled on transactions instead of debiting / crediting accounts \
+    → Support for complex transactions made up of several transfers
+    - Dedicated payer (from) and payee (to) fields (ledger only supports payee)
+- No misuse of accounts as categories / tags \
+    → Direct support for tags
+- Clear separation between
+    - Physical account (e.g. wallet, bank account)
+    - Entities (e.g. my mum, a company)
+    - Purpose of transaction (e.g. food, travel)
+- No hard-coded asset / liability connotation as it is viewpoint dependent \
+    → Choose viewpoint by setting the owner of the journal
+- Initial balances
+- High precision timestamps in ISO 8601 format
+- Reference external files (e.g. receipts, contracts, bank statements, …)
+- Safety checks
+    - BigInt fractional numbers to eliminate rounding errors
+    - Verifies exclusive use of predefined entities
+    - Checks in transactions match with verification balances
+    - Checks that referenced external files exist
+        and that all external files are referenced
+- Export to other formats for post-processing
+    - [Gnuplot] - For trends
+    - [(H)ledger Format] - For using (H)ledger exclusive features
+    - CSV and TSV - For further processing in spreadsheet software
+    - XLSX aka Excel - For further processing in spreadsheet software
+- Multi file support
+
+[YAML]: http://yaml.org
+[Gnuplot]: http://www.gnuplot.info
+[(H)ledger Format]: http://hledger.org/journal.html

docs_src/01_Installation.md

@@ -0,0 +1,18 @@
+## Installation
+
+Transity is distributed as a JavaScript bundle and can therefore
+be installed via [npm](https://npmjs.com):
+
+```sh
+npm install --global transity
+```
+
+or via [Yarn](https://yarnpkg.com):
+```sh
+yarn global add transity
+```
+
+or via [Bun](https://bun.sh):
+```sh
+bun install --global transity
+```

docs_src/02_Usage.md

@@ -0,0 +1,161 @@
+## Usage
+
+### Journal File Format
+
+A minimal journal file is a YAML file with following format:
+
+```yaml
+owner: anna
+commodities:
+  - id: €
+    name: Euro
+    alias:
+      - EUR
+    note: Currency used in the European Union
+    utc: '2017-04-02 19:33:53'
+
+entities:
+  - id: anna
+    name: Anna Smith
+    utc: '2017-04-02 19:33:28'
+    tags:
+      - person
+    accounts:
+      - id: wallet
+        name: Wallet
+        note: Anna's black wallet
+        utc: '2017-04-02 19:33:28'
+        tags:
+          - wallet
+
+  - id: evil-corp
+    name: Evil Corporation
+    utc: '2017-04-02 19:33:28'
+    note: The Evil Corporation in the United States of Evil
+    tags:
+      - company
+
+transactions:
+  - title: Purchase of evil machine
+    transfers:
+      - utc: '2017-02-17'
+        from: anna
+        to: evil-corp
+        amount: 50000 €
+      - utc: '2017-02-17'
+        from: evil-corp
+        to: anna
+        amount: 1 evil-machine
+```
+
+
+### Analyzing Journal Files
+
+#### Balance
+
+```shell
+$ transity balance examples/journal.yaml
+          anna       1        evil-machine
+                -49978.02     €
+           ben     -50        $
+                    -1.432592 BTC
+                  -100        €
+     evil-corp      -1        evil-machine
+                 50015        €
+      good-inc    -100        €
+  grocery-shop      11.97     €
+  john             371.04     €
+                    50        $
+                     1.432592 BTC
+      :default     219.99     €
+          giro      50        $
+                     1.432592 BTC
+                    85        €
+        wallet      66.05     €
+```
+
+If linked modules aren't exposed in your path you can also run
+
+```shell
+cli/main.js balance examples/journal.yaml
+```
+
+
+#### Help
+
+List complete usage manual by simply calling `transity` without any arguments.
+
+```shell
+$ transity
+
+Usage: transity <command> <path/to/journal.yaml>
+
+Command             Description
+------------------  ------------------------------------------------------------
+balance             Simple balance of all accounts
+transactions        All transactions and their transfers
+transfers           All transfers with one transfer per line
+entries             All individual deposits & withdrawals
+entries-by-account  All individual deposits & withdrawals grouped by account
+gplot               Code and data for gnuplot impulse diagram
+                    to visualize transfers of all accounts
+gplot-cumul         Code and data for cumuluative gnuplot step chart
+                    to visualize balance of all accounts
+```
+
+
+#### Transfers
+
+<img
+  src='images/screenshot-transfers.svg'
+  alt='Screenshot Transfers'
+  width='600'
+/>
+
+
+#### Plotting
+
+By default all accounts are plotted.
+To limit it to only a subsection use `awk` to filter the output.
+
+For example all transactions of Euro accounts:
+
+```bash
+transity gplot examples/journal.yaml \
+| awk '/^$/ || /(EOD|^set terminal)/ || /€/' \
+| gnuplot \
+| imgcat
+```
+
+Or all account balances of Euro accounts over time:
+
+```bash
+transity gplot-cumul examples/journal.yaml \
+| awk '/^$/ || /(EOD|^set terminal)/ || /€/' \
+| gnuplot \
+| imgcat
+```
+
+![Screenshot of cumulative account balance plot](./images/screenshot-plot.png)
+
+
+### Scripts
+
+Useful scripts leveraging other command line tools.
+
+#### Check Order of Entries
+
+Check if all entries are in a chronological order
+
+```sh
+ag --nonumbers "^    utc:" journals/main.yaml | tr -d "\'" | sort -c
+```
+
+
+### Tutorials
+
+- [cs007.blog] - Personal finance for engineers.
+- [principlesofaccounting.com] - Online tutorial on accounting.
+
+[cs007.blog]: https://cs007.blog
+[principlesofaccounting.com]: https://www.principlesofaccounting.com

docs_src/03_Import.md

@@ -0,0 +1,77 @@
+## Import
+
+### AI Powered
+
+We built a dedicated OpenAI GPT to convert any financial data
+(e.g. CSVs, bank statements, chat history, …) to a Transity journal file.
+
+Check it out at
+[chat.openai.com/g/g-aUph953Vj-transity](
+  https://chat.openai.com/g/g-aUph953Vj-transity).
+
+
+### From Ledger CLI
+
+Execute the included ledger2transity script:
+
+```shell
+./ledger2transity.sh examples/hledger.journal > transactions.csv
+```
+
+Convert `transactions.csv` to YAML with e.g. [browserling.com/tools/csv-to-yaml]
+
+[browserling.com/tools/csv-to-yaml]: https://browserling.com/tools/csv-to-yaml
+
+
+**Attention:**
+
+- Merge adjacent entries as each entry only debits / credits an account.
+  A transaction always involves 2 accounts (`from` and `to`).
+  (For expenses basically copy the ledger-account from the second entry
+  into the `from` field of the first entry)
+- `from` and `to` might be reversed for income
+  (depending on how the `payee` field was used)
+- Account names of Ledger-CLI are interpreted as tags
+  Transity understands accounts as **physical accounts**
+- The note is duplicated in the `tags` field.
+  There is no way to get only the tags in Ledger-CLI 😔
+
+
+### Scripts
+
+Transity includes a few scripts located at [./scripts](./scripts) to
+automate a Chrome browser to download data.
+
+
+### Retrieving Data from Banks
+
+It supports downloading CSV files of all
+transactions and converting them to journal
+files and retrieving the current account balance:
+
+```sh
+node scripts/transactions/hypovereinsbank.js > transactions.yaml
+```
+
+This will prompt you for your credentials and afterwards automate
+a headless Chrome instance to download and convert the data.
+
+Currently supported accounts for transactions:
+
+- [DKB Visa Card](https://dkb.de)
+- [DKB Giro Account](https://dkb.de)
+- [HypoVereinsbank](https://www.hypovereinsbank.de)
+- [MBS](https://mbs.de)
+
+Currently supported accounts for balances:
+
+- [AWS](https://aws.amazon.com)
+- [DKB](https://dkb.de)
+- [Fidor](https://fidor.de)
+- [Finvesto](https://finvesto.de)
+- [HypoVereinsbank](https://www.hypovereinsbank.de)
+- [MBS](https://mbs.de)
+- [PayPal](https://paypal.com)
+- [Deutsche Post Petty Cash](https://portokasse.deutschepost.de)
+
+Contributions are very welcome!