Skip to content

Commit 77ab998

Browse files
ad-siad-si
committed
Move all documentation to docs_src, build documentation pages
1 parent 8d6c41d commit 77ab998

24 files changed

+3099
-2404
lines changed

‎comparison.md

-63
This file was deleted.

‎docs_src/00_Features.md

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

‎docs_src/01_Installation.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
## Installation
2+
3+
Transity is distributed as a JavaScript bundle and can therefore
4+
be installed via [npm](https://npmjs.com):
5+
6+
```sh
7+
npm install --global transity
8+
```
9+
10+
or via [Yarn](https://yarnpkg.com):
11+
```sh
12+
yarn global add transity
13+
```
14+
15+
or via [Bun](https://bun.sh):
16+
```sh
17+
bun install --global transity
18+
```

‎docs_src/02_Usage.md

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
## Usage
2+
3+
### Journal File Format
4+
5+
A minimal journal file is a YAML file with following format:
6+
7+
```yaml
8+
owner: anna
9+
commodities:
10+
- id: €
11+
name: Euro
12+
alias:
13+
- EUR
14+
note: Currency used in the European Union
15+
utc: '2017-04-02 19:33:53'
16+
17+
entities:
18+
- id: anna
19+
name: Anna Smith
20+
utc: '2017-04-02 19:33:28'
21+
tags:
22+
- person
23+
accounts:
24+
- id: wallet
25+
name: Wallet
26+
note: Anna's black wallet
27+
utc: '2017-04-02 19:33:28'
28+
tags:
29+
- wallet
30+
31+
- id: evil-corp
32+
name: Evil Corporation
33+
utc: '2017-04-02 19:33:28'
34+
note: The Evil Corporation in the United States of Evil
35+
tags:
36+
- company
37+
38+
transactions:
39+
- title: Purchase of evil machine
40+
transfers:
41+
- utc: '2017-02-17'
42+
from: anna
43+
to: evil-corp
44+
amount: 50000 €
45+
- utc: '2017-02-17'
46+
from: evil-corp
47+
to: anna
48+
amount: 1 evil-machine
49+
```
50+
51+
52+
### Analyzing Journal Files
53+
54+
#### Balance
55+
56+
```shell
57+
$ transity balance examples/journal.yaml
58+
anna 1 evil-machine
59+
-49978.02 €
60+
ben -50 $
61+
-1.432592 BTC
62+
-100 €
63+
evil-corp -1 evil-machine
64+
50015 €
65+
good-inc -100 €
66+
grocery-shop 11.97 €
67+
john 371.04 €
68+
50 $
69+
1.432592 BTC
70+
:default 219.99 €
71+
giro 50 $
72+
1.432592 BTC
73+
85 €
74+
wallet 66.05 €
75+
```
76+
77+
If linked modules aren't exposed in your path you can also run
78+
79+
```shell
80+
cli/main.js balance examples/journal.yaml
81+
```
82+
83+
84+
#### Help
85+
86+
List complete usage manual by simply calling `transity` without any arguments.
87+
88+
```shell
89+
$ transity
90+
91+
Usage: transity <command> <path/to/journal.yaml>
92+
93+
Command Description
94+
------------------ ------------------------------------------------------------
95+
balance Simple balance of all accounts
96+
transactions All transactions and their transfers
97+
transfers All transfers with one transfer per line
98+
entries All individual deposits & withdrawals
99+
entries-by-account All individual deposits & withdrawals grouped by account
100+
gplot Code and data for gnuplot impulse diagram
101+
to visualize transfers of all accounts
102+
gplot-cumul Code and data for cumuluative gnuplot step chart
103+
to visualize balance of all accounts
104+
```
105+
106+
107+
#### Transfers
108+
109+
<img
110+
src='images/screenshot-transfers.svg'
111+
alt='Screenshot Transfers'
112+
width='600'
113+
/>
114+
115+
116+
#### Plotting
117+
118+
By default all accounts are plotted.
119+
To limit it to only a subsection use `awk` to filter the output.
120+
121+
For example all transactions of Euro accounts:
122+
123+
```bash
124+
transity gplot examples/journal.yaml \
125+
| awk '/^$/ || /(EOD|^set terminal)/ || /€/' \
126+
| gnuplot \
127+
| imgcat
128+
```
129+
130+
Or all account balances of Euro accounts over time:
131+
132+
```bash
133+
transity gplot-cumul examples/journal.yaml \
134+
| awk '/^$/ || /(EOD|^set terminal)/ || /€/' \
135+
| gnuplot \
136+
| imgcat
137+
```
138+
139+
![Screenshot of cumulative account balance plot](./images/screenshot-plot.png)
140+
141+
142+
### Scripts
143+
144+
Useful scripts leveraging other command line tools.
145+
146+
#### Check Order of Entries
147+
148+
Check if all entries are in a chronological order
149+
150+
```sh
151+
ag --nonumbers "^ utc:" journals/main.yaml | tr -d "\'" | sort -c
152+
```
153+
154+
155+
### Tutorials
156+
157+
- [cs007.blog] - Personal finance for engineers.
158+
- [principlesofaccounting.com] - Online tutorial on accounting.
159+
160+
[cs007.blog]: https://cs007.blog
161+
[principlesofaccounting.com]: https://www.principlesofaccounting.com

‎docs_src/03_Import.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
## Import
2+
3+
### AI Powered
4+
5+
We built a dedicated OpenAI GPT to convert any financial data
6+
(e.g. CSVs, bank statements, chat history, …) to a Transity journal file.
7+
8+
Check it out at
9+
[chat.openai.com/g/g-aUph953Vj-transity](
10+
https://chat.openai.com/g/g-aUph953Vj-transity).
11+
12+
13+
### From Ledger CLI
14+
15+
Execute the included ledger2transity script:
16+
17+
```shell
18+
./ledger2transity.sh examples/hledger.journal > transactions.csv
19+
```
20+
21+
Convert `transactions.csv` to YAML with e.g. [browserling.com/tools/csv-to-yaml]
22+
23+
[browserling.com/tools/csv-to-yaml]: https://browserling.com/tools/csv-to-yaml
24+
25+
26+
**Attention:**
27+
28+
- Merge adjacent entries as each entry only debits / credits an account.
29+
A transaction always involves 2 accounts (`from` and `to`).
30+
(For expenses basically copy the ledger-account from the second entry
31+
into the `from` field of the first entry)
32+
- `from` and `to` might be reversed for income
33+
(depending on how the `payee` field was used)
34+
- Account names of Ledger-CLI are interpreted as tags
35+
Transity understands accounts as **physical accounts**
36+
- The note is duplicated in the `tags` field.
37+
There is no way to get only the tags in Ledger-CLI 😔
38+
39+
40+
### Scripts
41+
42+
Transity includes a few scripts located at [./scripts](./scripts) to
43+
automate a Chrome browser to download data.
44+
45+
46+
### Retrieving Data from Banks
47+
48+
It supports downloading CSV files of all
49+
transactions and converting them to journal
50+
files and retrieving the current account balance:
51+
52+
```sh
53+
node scripts/transactions/hypovereinsbank.js > transactions.yaml
54+
```
55+
56+
This will prompt you for your credentials and afterwards automate
57+
a headless Chrome instance to download and convert the data.
58+
59+
Currently supported accounts for transactions:
60+
61+
- [DKB Visa Card](https://dkb.de)
62+
- [DKB Giro Account](https://dkb.de)
63+
- [HypoVereinsbank](https://www.hypovereinsbank.de)
64+
- [MBS](https://mbs.de)
65+
66+
Currently supported accounts for balances:
67+
68+
- [AWS](https://aws.amazon.com)
69+
- [DKB](https://dkb.de)
70+
- [Fidor](https://fidor.de)
71+
- [Finvesto](https://finvesto.de)
72+
- [HypoVereinsbank](https://www.hypovereinsbank.de)
73+
- [MBS](https://mbs.de)
74+
- [PayPal](https://paypal.com)
75+
- [Deutsche Post Petty Cash](https://portokasse.deutschepost.de)
76+
77+
Contributions are very welcome!

0 commit comments

Comments
 (0)