mirror of
https://github.com/Findus23/invoices.git
synced 2024-09-19 15:13:47 +02:00
142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
# Invoices
|
|
To generate invoices, you need multiple local configs. Your own information
|
|
should be present in `from.yaml`, the person (or company) you write the invoice
|
|
to should be present as a file in `recipients/<rname>.yaml`, where `rname` is
|
|
the selector. The specific information about this invoice should be in
|
|
`config.yaml`.
|
|
|
|
# More Features
|
|
If you need more features than are available here, take a look at [this version
|
|
from fkarg](https://github.com/fkarg/invoices).
|
|
|
|
|
|
## Your own information: from.yaml
|
|
Have a file called `from.yaml` with your own information structured like this:
|
|
|
|
### Field descriptions
|
|
| Field | Type | description |
|
|
|:---|:---:|:---|
|
|
| `name` | string | Your full name. |
|
|
| `address` | string | Your Address. Both street and number. |
|
|
| `zip` | int | Your area ZIP code. |
|
|
| `city` | string | The city you live in. |
|
|
| `cityShort` | string | Shortened version of your city name. |
|
|
| `countryDE` | strang | Name of your country in German, used for an invoice in German. |
|
|
| `countryEN` | strang | Name of your country in English, used for an invoice in English. |
|
|
| `IBAN` | string | The IBAN of your bank account. |
|
|
| `BIC` | string | The BIC of your bank account. |
|
|
| `bank` | string | The name of your bank. |
|
|
| `phone` | string | Optional. Your phone number. |
|
|
| `email` | string | Optional. Your mail address. |
|
|
| `url` | string | Optional. Your homepage. |
|
|
|
|
### Example
|
|
```from.yaml
|
|
name: <name>
|
|
address: <address>
|
|
zip: <zip>
|
|
city: <name of city>
|
|
cityShort: <short name of city>
|
|
countryDE: Deutschland
|
|
countryEN: Germany
|
|
IBAN: <IBAN>
|
|
BIC: <BIC>
|
|
bank: <name of bank>
|
|
```
|
|
|
|
It's no big deal to leave some of the fields empty.
|
|
|
|
## Clients: recipients/\<rname\>.yaml
|
|
For every clients `rname`, have a `recipients/<rname>.yaml` file structured
|
|
like this:
|
|
|
|
### Field descriptions
|
|
| Field | Type | description |
|
|
|:---|:---:|:---|
|
|
| `name` | string | Your clients name. |
|
|
| `address` | string | Your clients business address. Both street and number. |
|
|
| `zip` | int | ZIP code of your clients address. |
|
|
| `city` | string | City correlating to the zip code. |
|
|
| `country` | string | Country of your clients business address. |
|
|
|
|
### Example
|
|
```recipients/<rname>.yaml
|
|
name: <name>
|
|
address: <address>
|
|
zip: <zip>
|
|
city: <city>
|
|
country: <country>
|
|
```
|
|
|
|
|
|
## Config: config.yaml
|
|
The main config is in a file called `config.yaml`:
|
|
|
|
### Field descriptions
|
|
| Field | Type | description |
|
|
|:---|:---:|:---|
|
|
| `title` | string | Title of the invoice. |
|
|
| `description` | string | Description of the work you did. |
|
|
| `range` | string | Timeframe during which you accumulated the given number of hours. |
|
|
| `hours` | int | Number of hours you worked for the given timeframe and client. |
|
|
| `default_recipient` | string | Filename (before the `.yaml`) of your default client. |
|
|
| `last_id` | int | Since invoices need to have unique IDs, this number will be increased by one. After that, the config will be written back to the file. This deletes any prior comments. |
|
|
| `invoice_dir` | string | Directory in which the invoice will be generated. Needs to exist prior to execution. |
|
|
| `default_hourly_rate` | int | The hourly rate you bill for in this receipt. |
|
|
| `bank_fee` | int | Optional. Amount of bank fees you can invoice. |
|
|
|
|
### Example
|
|
```config.yaml
|
|
title: <invoice title>
|
|
description: <work description>
|
|
range: <timeframe in which you worked>
|
|
hours: <hours worked>
|
|
default_recipient: <rname>
|
|
last_id: <int>
|
|
invoice_dir: invoice # directory needs to exist
|
|
default_hourly_rate: <int>
|
|
```
|
|
|
|
## Structure
|
|
The directory structure of where you execute this script should look something
|
|
like this:
|
|
```
|
|
$ tree
|
|
.
|
|
├── invoice # content is generated, but folder needs to exist
|
|
│ ├── <id>
|
|
│ └── <id>
|
|
├── recipients
|
|
│ ├── <rname>.yaml
|
|
│ └── <rname>.yaml
|
|
├── from.yaml
|
|
└── config.yaml
|
|
```
|
|
|
|
## Setup
|
|
Make sure to install poetry first.
|
|
|
|
### Nix
|
|
`nix-env -iA nixpkgs.poetry`
|
|
|
|
### Other
|
|
According to [their website](https://python-poetry.org/docs/#installation),
|
|
this is the recommended way of installation:
|
|
`curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python`
|
|
|
|
### Install dependencies
|
|
Make sure to switch to a virtual environment prior to installing dependencies.
|
|
```
|
|
$ virtualenv -p python3 .venv
|
|
$ source .venv/bin/activate
|
|
$ poetry install # install dependencies
|
|
```
|
|
|
|
|
|
## Usage
|
|
|
|
```
|
|
$ python main.py create
|
|
... # you will be asked for details and further information interactively
|
|
$ python main.py compile
|
|
```
|