Skip to content

Commit

Permalink
📝 mkdocs
Browse files Browse the repository at this point in the history 
#105
  • Loading branch information
@juftin
juftin authored Dec 17, 2023
1 parent 0f19b41 commit 7e8576c
Show file tree
Hide file tree
Showing 36 changed files with 864 additions and 1,105 deletions.
57 changes: 14 additions & 43 deletions .github/workflows/release.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@ jobs:
python-version: '3.11'
- name: Install Hatch
run: |
python -m pip install --upgrade pip
python -m pip install --upgrade pip wheel
python -m pip install -q hatch pre-commit
python -m pip install -q "${{ github.workspace }}"
hatch --version
- name: Release
run: hatch run gen:release
Expand All @@ -37,60 +38,30 @@ jobs:
GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com

github-pages-publish:
runs-on: ubuntu-latest
needs: release
if: github.ref == 'refs/heads/main' && github.repository_owner == 'juftin'
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout Latest Changes
uses: actions/checkout@v3
with:
path: ${{ github.workspace }}/main
ref: ${{ github.ref }}
fetch-depth: 0
- name: Create gh-pages if not exists
working-directory: ${{ github.workspace }}/main
run: |
git checkout gh-pages || git checkout -b gh-pages
git push --set-upstream origin gh-pages || true
git checkout main --
- name: Checkout gh-pages Branch
uses: actions/checkout@v4
with:
path: ${{ github.workspace }}/github-pages
ref: gh-pages
ref: ${{ github.ref }}
fetch-depth: 0
- name: Set up Python Environment
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install Hatch
working-directory: ${{ github.workspace }}/main
run: |
python -m pip install --upgrade pip
python -m pip install -q hatch
python -m pip install --upgrade pip wheel
python -m pip install -q hatch pre-commit
python -m pip install -q "${{ github.workspace }}"
hatch --version
- name: Documentation Generation
working-directory: ${{ github.workspace }}/main
run: |
hatch run docs:build
- name: Setup Git Config
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"
- name: Get Commit SHA from main
working-directory: ${{ github.workspace }}/main
run: |
COMMIT_SHA=$(git rev-parse HEAD)
PROJECT_VERSION=$(hatch version)
echo PROJECT_VERSION=${PROJECT_VERSION} >> $GITHUB_ENV
echo "COMMIT_SHA=${COMMIT_SHA}" >> ${GITHUB_ENV}
- name: Commit Changes to gh-pages Branch
working-directory: ${{ github.workspace }}/github-pages
- name: Set Up GitHub Actions User
run: |
git rm -rf . || true
cp -R ${{ github.workspace }}/main/docs/_build/html/* ${PWD}
touch .nojekyll
cp ${{ github.workspace }}/main/docs/README.md .
git add .
git diff-index --quiet HEAD || git commit -m "GitHub Pages - ${{ env.PROJECT_VERSION }} - ${{ env.COMMIT_SHA }}"
git push origin gh-pages --force
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Deploy Documentation Changes
run: hatch run docs:gh-deploy --force
36 changes: 24 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,23 @@
# lunchable
<h1 align="center">lunchable</h1>

<div align="center">
<a href="https://github.com/juftin/lunchable">
<a href="https://github.com/juftin/lunchable">
<img src=https://i.imgur.com/FyKDsG3.png
width="400" alt="lunchable">
</a>
width="400" alt="lunchable"> </a>
</div>

[![Lunchable Version](https://img.shields.io/pypi/v/lunchable?color=blue&label=lunchable)](https://github.com/juftin/lunchable)
[![PyPI](https://img.shields.io/pypi/pyversions/lunchable)](https://pypi.python.org/pypi/lunchable/)
[![Docker Image Version](https://img.shields.io/docker/v/juftin/lunchable?color=blue&label=docker&logo=docker)](https://hub.docker.com/r/juftin/lunchable)
[![Testing Status](https://github.com/juftin/lunchable/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/juftin/lunchable/actions/workflows/tests.yaml?query=branch%3Amain)
[![GitHub License](https://img.shields.io/github/license/juftin/lunchable?color=blue&label=License)](https://github.com/juftin/lunchable/blob/main/LICENSE)
<p align="center">
<a href="https://github.com/juftin/lunchable"><img src="https://img.shields.io/pypi/v/lunchable?color=blue&label=lunchable" alt="PyPI"></a>
<a href="https://pypi.python.org/pypi/lunchable/"><img src="https://img.shields.io/pypi/pyversions/lunchable" alt="PyPI - Python Version"></a>
<a href="https://hub.docker.com/r/juftin/lunchable"><img src="https://img.shields.io/docker/v/juftin/lunchable?color=blue&label=docker&logo=docker" alt="Docker Image Version"></a>
<a href="https://github.com/juftin/lunchable/actions/workflows/tests.yaml?query=branch%3Amain"><img src="https://github.com/juftin/lunchable/actions/workflows/tests.yaml/badge.svg?branch=main" alt="Testing Status"></a>
<a href="https://github.com/juftin/lunchable/blob/main/LICENSE"><img src="https://img.shields.io/github/license/juftin/lunchable?color=blue&label=License" alt="GitHub License"></a>
<a href="https://github.com/pypa/hatch"><img src="https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg" alt="Hatch project"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://github.com/pre-commit/pre-commit"><img src="https://img.shields.io/badge/pre--commit-enabled-lightgreen?logo=pre-commit" alt="pre-commit"></a>
<a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="semantic-release"></a>
<a href="https://gitmoji.dev"><img src="https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg" alt="Gitmoji"></a>
</p>

**lunchable** is a Python Client for the [Lunch Money Developer API](https://lunchmoney.dev). It's
built on top of [pydantic](https://github.com/pydantic/pydantic) and [httpx](https://github.com/encode/httpx/),
Expand All @@ -27,16 +33,18 @@ pip install lunchable
### Usage

```python
from typing import Any, Dict, List
from __future__ import annotations

from typing import Any

from lunchable import LunchMoney
from lunchable.models import TransactionObject

lunch = LunchMoney(access_token="xxxxxxxxxxx")
transactions: List[TransactionObject] = lunch.get_transactions()
transactions: list[TransactionObject] = lunch.get_transactions()

first_transaction: TransactionObject = transactions[0]
transaction_as_dict: Dict[str, Any] = first_transaction.model_dump()
transaction_as_dict: dict[str, Any] = first_transaction.model_dump()
```

```shell
Expand All @@ -45,6 +53,8 @@ lunchable transactions get --limit 5
lunchable http -X GET https://dev.lunchmoney.app/v1/assets
```

<!--skip-->

### Check out the [**Docs**](https://juftin.com/lunchable/)

### Looking to contribute? See the [Contributing Guide](docs/source/contributing.md)
Expand All @@ -58,3 +68,5 @@ lunchable http -X GET https://dev.lunchmoney.app/v1/assets
<br/>

[<p align="center" ><img src="https://raw.githubusercontent.com/juftin/juftin/main/static/juftin.png" width="60" height="60" alt="juftin logo"> </p>](https://github.com/juftin)

<!--skip-->
20 changes: 0 additions & 20 deletions docs/Makefile
View file

This file was deleted.

9 changes: 0 additions & 9 deletions docs/README.md
View file

This file was deleted.

12 changes: 12 additions & 0 deletions docs/cli.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# lunchable CLI

```bash exec="on" source="above" result="markdown"
lunchable --help
```

::: mkdocs-click
:module: lunchable._cli
:command: cli
:prog_name: lunchable
:style: table
:list_subcommands: True
66 changes: 64 additions & 2 deletions docs/source/contributing.md → docs/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,26 @@

## Environment Setup

1. Install [hatch](https://github.com/pypa/hatch)
> TIP: **pipx**
>
> This documentaion uses [pipx] to
> install and manage non-project command line tools like `hatch` and
> `pre-commit`. If you don't already have `pipx` installed, make sure to
> see their [documentation](https://pypa.github.io/pipx/installation/).
> If you prefer not to use `pipx`, you can use `pip` instead.
1. Install [hatch](https://hatch.pypa.io/latest/)

```shell
pipx install hatch
```

> NOTE: **pre-commit**
>
> Hatch will attempt to set up pre-commit hooks for you using
> [pre-commit]. If you don't already,
> make sure to install pre-commit as well: `pipx install pre-commit`
2. Build the Virtual Environment
```shell
Expand All @@ -18,7 +32,7 @@
They can be located by name with the `env find` command:
```shell
hatch env find default
hatch env find test
```
4. Activate the Virtual Environment
Expand Down Expand Up @@ -48,6 +62,54 @@ These features include virtual environment management and the organization of co
scripts like linting and testing. All the operations in hatch take place in one
of its managed virtual environments.

Hatch has a variety of environments, to see them simply ask hatch:

```bash exec="on" result="markdown" source="tabbed-left" tabs="hatch CLI|Output"
hatch env show
```

That above command will tell you that there are five environments that
you can use:

- `default`
- `docs`
- `gen`
- `lint`
- `test`

Each of these environments has a set of commands that you can run.
To see the commands for a specific environment, run:

```bash exec="on" result="markdown" source="tabbed-left" tabs="hatch CLI|Output"
hatch env show default
```

Here we can see that the `default` environment has the following commands:

- `cov`
- `test`

The one that we're interested in is `cov`, which will run the tests
for the project.
```bash
hatch run cov
```
Since `cov` is in the default environment, we can run it without
specifying the environment. However, to run the `serve` command in the
`docs` environment, we need to specify the environment:
```bash
hatch run docs:serve
```
You can see what scripts are available using the `env show` command
```bash exec="on" result="markdown" source="tabbed-left" tabs="hatch CLI|Output"
hatch env show docs
```
## Committing Code
This project uses [pre-commit] to run a set of
Expand Down
36 changes: 36 additions & 0 deletions docs/gen_pages.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
"""
Generate the code reference pages and navigation.
"""

import logging
from pathlib import Path

import mkdocs_gen_files

logger = logging.getLogger(__name__)

project_dir = Path(__file__).resolve().parent.parent
source_code = project_dir.joinpath("lunchable")

for path in sorted(source_code.rglob("*.py")):
module_path = path.relative_to(project_dir).with_suffix("")
doc_path = path.relative_to(source_code).with_suffix(".md")
full_doc_path = Path("reference", doc_path)

parts = tuple(module_path.parts)
if parts[-1] == "__init__":
parts = parts[:-1]
doc_path = doc_path.with_name("index.md")
full_doc_path = full_doc_path.with_name("index.md")
elif parts[-1] == "__main__":
continue
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
fd.write(f"# `{parts[-1]}`\n\n::: {'.'.join(parts)}")

mkdocs_gen_files.set_edit_path(full_doc_path, path)

# Exclude parts that are between two exact `<!--skip-->` lines
readme_content = Path("README.md").read_text()
readme_content = "\n".join(readme_content.split("\n<!--skip-->\n")[::2])
with mkdocs_gen_files.open("index.md", "w") as index_file:
index_file.write(readme_content)
72 changes: 72 additions & 0 deletions docs/interacting.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# LunchMoney

The `LunchMoney` client is the main entrypoint for interacting with the Lunch Money API.
It defaults to inheriting the `LUNCHMONEY_ACCESS_TOKEN` environment variable, but can be
created with an explicit `access_token` parameter.

```python
from lunchable import LunchMoney

lunch = LunchMoney(access_token="xxxxxxxxxxx")
```

## Methods

| HTTP Verb | Name | Description |
|-----------|--------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| GET | [get_assets](#lunchable.LunchMoney.get_assets) | Get Manually Managed Assets |
| GET | [get_budgets](#lunchable.LunchMoney.get_budgets) | Get Monthly Budgets |
| GET | [get_categories](#lunchable.LunchMoney.get_categories) | Get Spending categories |
| GET | [get_category](#lunchable.LunchMoney.get_category) | Get single category |
| GET | [get_crypto](#lunchable.LunchMoney.get_crypto) | Get Crypto Assets |
| GET | [get_plaid_accounts](#lunchable.LunchMoney.get_plaid_accounts) | Get Plaid Synced Assets |
| GET | [get_recurring_expenses](#lunchable.LunchMoney.get_recurring_expenses) | Get Recurring Expenses |
| GET | [get_tags](#lunchable.LunchMoney.get_tags) | Get Spending Tags |
| GET | [get_transaction](#lunchable.LunchMoney.get_transaction) | Get a Transaction by ID |
| GET | [get_transactions](#lunchable.LunchMoney.get_transactions) | Get Transactions Using Criteria |
| GET | [get_user](#lunchable.LunchMoney.get_user) | Get Personal User Details |
| POST | [insert_asset](#lunchable.LunchMoney.insert_asset) | Create a single (manually-managed) asset |
| POST | [insert_category](#lunchable.LunchMoney.insert_category) | Create a Spending Category |
| POST | [insert_category_group](#lunchable.LunchMoney.insert_category_group) | Create a Spending Category Group |
| POST | [insert_into_category_group](#lunchable.LunchMoney.insert_into_category_group) | Add to a Category Group |
| POST | [insert_transaction_group](#lunchable.LunchMoney.insert_transaction_group) | Create a Transaction Group of Two or More Transactions |
| POST | [insert_transactions](#lunchable.LunchMoney.insert_transactions) | Create One or Many Lunch Money Transactions |
| POST | [unsplit_transactions](#lunchable.LunchMoney.unsplit_transactions) | Unsplit Transactions |
| PUT | [upsert_budget](#lunchable.LunchMoney.upsert_budget) | Upsert a Budget for a Category and Date |
| PUT | [update_asset](#lunchable.LunchMoney.update_asset) | Update a Single Asset |
| PUT | [update_category](#lunchable.LunchMoney.update_category) | Update a single category |
| PUT | [update_crypto](#lunchable.LunchMoney.update_crypto) | Update a Manual Crypto Asset |
| PUT | [update_transaction](#lunchable.LunchMoney.update_transaction) | Update a Transaction |
| DELETE | [remove_budget](#lunchable.LunchMoney.remove_budget) | Unset an Existing Budget for a Particular Category in a Particular Month |
| DELETE | [remove_category](#lunchable.LunchMoney.remove_category) | Delete a single category |
| DELETE | [remove_category_force](#lunchable.LunchMoney.remove_category_force) | Forcefully delete a single category |
| DELETE | [remove_transaction_group](#lunchable.LunchMoney.remove_transaction_group) | Delete a Transaction Group |

## Low Level Methods

| Name | Description |
|------------------------------------------------------------|-------------------------------------------------------|
| [request](#lunchable.LunchMoney.request) | Make an HTTP request |
| [arequest](#lunchable.LunchMoney.arequest) | Make an async HTTP request |
| [process_response](#lunchable.LunchMoney.process_response) | Process a Lunch Money response and raise any errors |
| [make_request](#lunchable.LunchMoney.make_request) | Make an HTTP request and `process` its response |
| [amake_request](#lunchable.LunchMoney.amake_request) | Make an async HTTP request and `process` its response |

## Attributes

| Name | Description |
|------------------------------------------------------|----------------------------------|
| [async_session](#lunchable.LunchMoney.async_session) | Authenticated Async HTTPX Client |
| [session](#lunchable.LunchMoney.session) | Authenticated HTTPX Client |

## Class Documentation

::: lunchable.LunchMoney
handler: python
options:
show_bases: false
allow_inspection: true
inherited_members: true
group_by_category: true
heading_level: 3
show_source: false
Loading

0 comments on commit 7e8576c

Please sign in to comment.