Refactor documentation to MkDocs

README.md

@@ -4,90 +4,18 @@
 [![pypi version](https://img.shields.io/pypi/v/beancount-multitool)](https://pypi.org/project/beancount-multitool/)
 ![python version required](https://img.shields.io/pypi/pyversions/beancount-multitool)
 ![static coverage badge](https://img.shields.io/badge/Coverage-89%25-blue)
+[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
 
 [Beancount Multitool](https://github.com/rlan/beancount-multitool/) is a command-line-interface (CLI) tool that converts financial data from financial institutions to Beancount files.
 
-The following institutions are supported:
+The following financial institutions are supported:
 
 * Japan
   * [JA Bank ＪＡネットバンク](https://www.jabank.jp/)
   * [Rakuten Card 楽天カード](https://www.rakuten-card.co.jp/)
   * [Rakuten Bank 楽天銀行](https://www.rakuten-bank.co.jp/)
   * [SBI Shinsei Bank 新生銀行](https://www.sbishinseibank.co.jp/)
 
-What these scripts __can__ do:
+To get started, see the [documentation](https://rlan.github.io/beancount-multitool).
 
-* Read raw CSV files downloaded from each institution's website.
-* Label transactions with different sub-accounts, e.g., `Expenses:JP:Food:Grocery` or `Expenses:JP:Food:Restaurant`.
-  * Documentation is incoming.
-* Label unknown transactions to respective account types.
-  * Debit: `Expenses:JP:Unknown:NameOfInstitution`
-  * Credit: `Income:JP:Unknown:NameOfInstitution`
-
-What these scripts __can not__ (yet) do:
-
-* To be added.
-
-Installation:
-
-```sh
-pip install beancount-multitool
-```
-
-Usage:
-
-```sh
-bean-mt --help
-```
-
-```txt
-Usage: bean-mt [OPTIONS] NAME CONFIG DATA
-
-  Read financial data and output a Beancount file.
-
-  NAME is the name of the financial institution. See Note below for a list of
-  supported names.
-
-  CONFIG is a .toml file with run-time configurations, e.g. config.toml.
-
-  DATA is the raw financial data downloaded from NAME, e.g. input.csv.
-
-Options:
-  --output PATH  Resulting Beancount file
-  --version      Show the version and exit.
-  --help         Show this message and exit.
-
-  Note: supported names of financial institutions: ['ja_bank', 'rakuten_bank',
-  'rakuten_card', 'shinsei_bank']
-```
-
-Example:
-
-```sh
-bean-mt rakuten_bank config.toml 2024-01.csv --output 2024-01.bean
-```
-
-Workflow:
-
-1. Download the raw CSV files from a financial institutions.
-2. Run `bean-mt`.
-3. Include the `output.bean` file in my ledger.
-4. Manually edit that Beancount file to my needs.
-
-config.toml:
-
-There is a default config.toml per financial institutions. Examples are in the test [data folder](tests/data).
-
-## Requirements
-
-* Python 3.9 or higher.
-
-## More
-
-* [Todo](todo.md)
-* [Changelog](changelog.md)
-* [Development](development.md)
-
-## License
-
-MIT License
+License: MIT

docs/reference/development.md

@@ -0,0 +1,87 @@
+# Development
+
+Instructions for developers.
+
+## On macOS
+
+Install
+
+* [Homebrew](https://brew.sh/)
+
+* [pyenv](https://github.com/pyenv/pyenv) and [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)
+
+  ```sh
+  brew install pyenv pyenv-virtualenv
+  ```
+
+* [pipx](https://github.com/pypa/pipx)
+
+  ```sh
+  brew install pipx
+  ```
+
+* [Poetry](https://github.com/python-poetry/poetry)
+
+  ```sh
+  pipx install poetry
+  ```
+
+* [ruff](https://github.com/astral-sh/ruff)
+
+  ```sh
+  brew install ruff
+  ```
+
+Similar to this [setup](https://github.com/Hasenpfote/python-poetry-example?tab=readme-ov-file), but no tox and uses ruff.
+
+## Development
+
+Get repo:
+
+```sh
+git clone
+```
+
+Install development environment:
+
+```sh
+poetry install
+```
+
+Launch virtualenv:
+
+```sh
+poetry shell
+```
+
+Code formatting:
+
+```sh
+poetry run ruff format
+```
+
+Linter:
+
+```sh
+poetry run ruff check
+```
+
+Test with coverage:
+
+```sh
+pytest --cov --cov-report term
+  ```
+
+## Publish checklist
+
+Ref: https://www.digitalocean.com/community/tutorials/how-to-publish-python-packages-to-pypi-using-poetry-on-ubuntu-22-04
+
+* [ ] Bump version
+    * [ ] `pyproject.toml`
+    * [ ] `src/beancount_multitool/\_\_version\_\_.py`
+    * [ ] Update [changelog](changelog.md)
+* [ ] Run local tests and coverage.
+    * [ ] Update coverage number in project `README.md`.
+* [ ] `git commit` and check that GitHub Action tests succeed.
+* [ ] `poetry build`
+* [ ] `poetry publish`

todo.md → docs/reference/todo.md

@@ -1,18 +1,18 @@
 # Todo
 
 * [x] Identify and label transactions to user-defined sub-accounts.
-  * [ ] Update docs.
+    * [x] Update docs.
+* [ ] Usage documentation.
+    * [x] basic
 * [x] Make `bean-mt`: a cli program.
 * [x] Use pytest.
 * [x] Add coverage to pytest.
-  * https://stackoverflow.com/a/65697914
+    * https://stackoverflow.com/a/65697914
 * [x] Location of default config toml
 * [x] Static coverage number.
 * [x] poetry, pytest using GitHub actions.
-* [ ] Control number of significant digits printed for `amount` in [`as_transaction()`](src/beancount_multitool/as_transaction.py).
-
+* [ ] Control number of significant digits printed for `amount` in `as_transaction()`.
 * [ ] Code coverage using GitHub actions.
-  * https://github.com/marketplace/actions/pytest-coverage-comment
+    * https://github.com/marketplace/actions/pytest-coverage-comment
 * [ ] Add contribution guidelines.
 * [ ] Documentation on how to obtain CSV files from the supported financial institution.
-* [ ] Usage documentation.

mkdocs.yml

@@ -47,6 +47,9 @@ nav:
   - Reference:
     - reference/data_model.md
     - reference/new_importer.md
+    - reference/changelog.md
+    - reference/development.md
+    - reference/todo.md
 
 repo_url: https://github.com/rlan/beancount-multitool
 repo_name: rlan/beancount-multitool
@@ -59,3 +62,6 @@ markdown_extensions:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format
+  - def_list
+  - pymdownx.tasklist:
+      custom_checkbox: true