docs: add poetry docs

docs/POETRY_JUPYTER_SETUP.md

@@ -0,0 +1,51 @@
+# Connecting Poetry Environment with Jupyter Notebook
+
+This guide provides simple steps to connect a Poetry-managed environment to Jupyter Notebook.
+
+## Steps
+
+1. **Activate the Poetry Environment**
+
+   First, navigate to your project directory and activate the Poetry shell:
+
+   ```bash
+   poetry shell
+   ```
+
+2. **Install Jupyter as a Development Dependency**
+
+   If Jupyter is not already installed, add it as a development dependency:
+
+   ```bash
+   poetry add --group dev jupyter
+   ```
+
+3. **Register the Poetry Environment as a Jupyter Kernel**
+
+   Run this command to make the Poetry environment available as a Jupyter kernel:
+
+   ```bash
+   python -m ipykernel install --user --name=llmdataparser-env --display-name "Python (LLMDataParser)"
+   ```
+
+   - `--name=llmdataparser-env`: Assigns a name to the kernel.
+   - `--display-name "Python (LLMDataParser)"`: Sets the display name seen in Jupyter.
+
+4. **Start Jupyter Notebook**
+
+   Launch Jupyter Notebook from the Poetry shell:
+
+   ```bash
+   jupyter notebook
+   ```
+
+5. **Select the Poetry Kernel in Jupyter**
+
+   - Open a notebook in Jupyter.
+   - Go to "Kernel" > "Change kernel" and select **Python (LLMDataParser)** from the list.
+
+   This connects the notebook to your Poetry environment.
+
+---
+
+You’re now set up to use your Poetry environment within Jupyter Notebook!

docs/POETRY_USAGE.md

@@ -0,0 +1,158 @@
+# Poetry Usage Guide
+
+This guide provides instructions on how to use [Poetry](https://python-poetry.org/) to manage dependencies, install packages, and prepare your project for both development and production environments.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installing Poetry](#installing-poetry)
+- [Using Poetry in Development](#using-poetry-in-development)
+  - [Installing Dependencies](#installing-dependencies)
+  - [Updating Dependencies](#updating-dependencies)
+  - [Adding and Removing Dependencies](#adding-and-removing-dependencies)
+  - [Synchronizing Dependencies](#synchronizing-dependencies)
+- [Using Poetry in Production](#using-poetry-in-production)
+  - [Locking Dependencies](#locking-dependencies)
+  - [Installing from `poetry.lock`](#installing-from-poetrylock)
+- [Poetry Commands Summary](#poetry-commands-summary)
+
+---
+
+## Overview
+
+Poetry is a dependency manager and build tool for Python projects. It simplifies managing dependencies, creating virtual environments, and ensuring version consistency between development and production environments. Poetry relies on two files:
+
+- **`pyproject.toml`**: Defines the dependencies and configuration.
+- **`poetry.lock`**: Locks dependencies to specific versions to ensure consistency.
+
+---
+
+## Installing Poetry(macOS only)
+
+To install Poetry, use the following command:
+
+```bash
+brew install poetry
+```
+
+Refer to the [Poetry documentation](https://python-poetry.org/docs/#installation) for more options and OS-specific installation instructions.
+
+---
+
+## Using Poetry in Development
+
+### Installing Dependencies
+
+In development, install dependencies specified in `pyproject.toml`:
+
+1. Navigate to the project directory:
+
+   ```bash
+   cd path/to/project
+   ```
+
+2. Run:
+   ```bash
+   poetry install
+   ```
+
+This command creates a virtual environment, installs all dependencies, and ensures they are compatible with the Python version specified.
+
+### Updating Dependencies
+
+During development, you can update dependencies by editing `pyproject.toml` directly and then running:
+
+```bash
+poetry install
+```
+
+This will apply any changes and update the environment without manually adding each dependency.
+
+### Adding and Removing Dependencies
+
+- **Add a New Dependency**:
+
+  ```bash
+  poetry add <package-name>
+  ```
+
+  Example:
+
+  ```bash
+  poetry add requests
+  ```
+
+- **Add a Development Dependency** (only used for development/testing):
+
+  ```bash
+  poetry add --group dev <package-name>
+  ```
+
+  Example:
+
+  ```bash
+  poetry add --group dev pytest
+  ```
+
+- **Remove a Dependency**:
+  ```bash
+  poetry remove <package-name>
+  ```
+
+### Synchronizing Dependencies
+
+If the `pyproject.toml` or `poetry.lock` files are updated (e.g., after pulling changes), run:
+
+```bash
+poetry install
+```
+
+This keeps your environment synchronized with any updates made to the dependency files.
+
+---
+
+## Using Poetry in Production
+
+### Locking Dependencies
+
+To lock dependencies for production use, run:
+
+```bash
+poetry lock
+```
+
+This creates or updates `poetry.lock`, which pins each dependency to a specific version. This lock file should be used to maintain consistency in production.
+
+### Installing from `poetry.lock`
+
+In production, use `poetry.lock` to ensure exact dependency versions:
+
+1. Install only the required (non-development) dependencies:
+   ```bash
+   poetry install --no-dev
+   ```
+
+This ensures that dependencies are installed exactly as defined in `poetry.lock`.
+
+---
+
+## Poetry Commands Summary
+
+| Command                        | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| `poetry install`               | Installs dependencies from `pyproject.toml` or `poetry.lock`. |
+| `poetry add <package-name>`    | Adds a new dependency and updates `pyproject.toml`.           |
+| `poetry add --group dev <pkg>` | Adds a development-only dependency.                           |
+| `poetry remove <package-name>` | Removes a dependency and updates `pyproject.toml`.            |
+| `poetry update`                | Updates all dependencies to their latest compatible versions. |
+| `poetry lock`                  | Locks dependencies to specific versions for production.       |
+| `poetry shell`                 | Activates the Poetry-managed virtual environment.             |
+
+---
+
+## Additional Resources
+
+- **Poetry Documentation**: [https://python-poetry.org/docs/](https://python-poetry.org/docs/)
+- **GitHub Repository**: [https://github.com/python-poetry/poetry](https://github.com/python-poetry/poetry)
+
+For further help, please refer to the [Poetry documentation](https://python-poetry.org/docs/).