📝 mkdocs wip

juftin · Dec 16, 2023 · 370ce9f · 370ce9f
1 parent fdc7e0d
commit 370ce9f
Show file tree

Hide file tree

Showing 42 changed files with 876 additions and 1,116 deletions.
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -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
@@ -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
+            uses: actions/setup-python@v4
             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
diff --git a/README.md b/README.md
@@ -2,16 +2,23 @@
 
 <div align="center">
 <a href="https://github.com/juftin/lunchable">
-  <img src=https://i.imgur.com/FyKDsG3.png
+  <img src=https://raw.githubusercontent.com/juftin/lunchable/main/docs/source/_static/lunchable.png
     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/),
@@ -27,16 +34,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
@@ -45,6 +54,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)
@@ -58,3 +69,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-->
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,8 @@
+# lunchable CLI
+
+::: mkdocs-click
+    :module: lunchable._cli
+    :command: cli
+    :prog_name: lunchable
+    :style: table
+    :list_subcommands: True
diff --git a/docs/source/contributing.md → docs/contributing.md b/docs/source/contributing.md → docs/contributing.md
@@ -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
@@ -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
@@ -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

diff --git a/docs/gen_pages.py b/docs/gen_pages.py
@@ -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)
diff --git a/docs/interacting.md b/docs/interacting.md
@@ -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                                    |
+|------------------------------------------------------------|------------------------------------------------|
+| [amake_request](#lunchable.LunchMoney.amake_request)       | Make an async HTTP Request and return its data |
+| [arequest](#lunchable.LunchMoney.arequest)                 | Make an async HTTP Request                     |
+| [make_request](#lunchable.LunchMoney.make_request)         | Make an HTTP Request and return its data       |
+| [process_response](#lunchable.LunchMoney.process_response) | Process a Lunch Money Response                 |
+| [request](#lunchable.LunchMoney.request)                   | Make an HTTP Request                           |
+
+## 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