Feat: add documentation (MkDocs) (#4)

## Summary
add MkDocs-based documentation for the TinyBear project,
including a minimal and user-friendly configuration for deployment to
GitHub Pages under the /tinybear subpath.

Author: lemontree210

.github/workflows/deploy.yml

@@ -0,0 +1,28 @@
+name: Deploy MkDocs to GitHub Pages (gh-pages branch)
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Install dependencies
+        run: |
+          pip install mkdocs mkdocs-material
+      - name: Build docs
+        run: |
+          mkdocs build --site-dir site
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site

docs/api.md

@@ -0,0 +1,209 @@
+# API Reference
+
+---
+
+## tinybear.csv_xls
+
+### append_empty_column_to_csv
+```python
+def append_empty_column_to_csv(path_to_file: Path, name_of_new_column: str, delimiter: CSVDelimiter = ",", custom_path_to_output_file: Optional[Path] = None) -> None:
+```
+Adds empty column (as last column) to CSV file. **Overwrites file**, but optional output path can be specified to create a new file.
+
+Raises:
+- ValueError if column name already exists in file.
+- FileExistsError if custom output file is specified and already exists.
+
+---
+
+### check_csv_for_malformed_rows
+```python
+def check_csv_for_malformed_rows(path_to_file: Path) -> None:
+```
+Checks whether all rows in CSV file have the same number of columns. Throws IndexError if they do not.
+
+---
+
+### check_csv_for_repetitions_in_column
+```python
+def check_csv_for_repetitions_in_column(path_to_file: Path, column_name: str) -> None:
+```
+Throws ValueError if there are repetitions in given column of given file.
+
+---
+
+### convert_xls_to_csv
+```python
+def convert_xls_to_csv(path_to_input_excel_file: Path, sheet_name: str, path_to_output_csv_file: Path, delimiter: CSVDelimiter = ",", overwrite: bool = True) -> None:
+```
+Converts sheet from Excel file to CSV format.
+
+---
+
+### read_column_from_csv
+```python
+def read_column_from_csv(path_to_file: Path, column_name: str) -> list[str]:
+```
+Reads one column from CSV file. Column name is taken from the top row. Raises KeyError if no such column exists.
+
+---
+
+### read_dicts_from_csv
+```python
+def read_dicts_from_csv(path_to_file: Path, delimiter: CSVDelimiter = ",") -> list[dict[str, str]]:
+```
+Reads CSV as list of dictionaries (top row is considered key).
+
+---
+
+### read_dict_from_2_csv_columns
+```python
+def read_dict_from_2_csv_columns(path_to_file: Path, key_col: str, val_col: str, delimiter: CSVDelimiter = ",") -> dict[str, str]:
+```
+Reads CSV and returns dict mapping keys from key_col to values from val_col.
+
+---
+
+### read_dicts_from_xls
+```python
+def read_dicts_from_xls(path_to_file: Path, sheet_name: str) -> list[dict[str, str]]:
+```
+Reads XLS sheet as list of dictionaries (top row as key).
+
+---
+
+### read_plain_rows_from_csv
+```python
+def read_plain_rows_from_csv(path_to_file: Path, delimiter: CSVDelimiter = ",", remove_1st_row: bool = False) -> list[list[str]]:
+```
+Reads plain rows (list of lists) from CSV.
+
+---
+
+### remove_rows_with_given_content_in_lookup_column
+```python
+def remove_rows_with_given_content_in_lookup_column(rows: list[dict[str, str]], lookup_column: str, match_value: str) -> tuple[list[dict[str, str]], tuple[int, ...]]:
+```
+Remove rows where lookup_column matches match_value. Returns (new list, indices of removed rows).
+
+---
+
+### write_csv
+```python
+def write_csv(rows, path_to_file: Path, overwrite: bool, delimiter: CSVDelimiter) -> None:
+```
+Writes rows (various formats) to CSV file. Adds header if writing dicts/NamedTuples.
+
+---
+
+## tinybear.json_toml_yaml
+
+### check_yaml_file
+```python
+def check_yaml_file(path_to_file: Path, verbose: bool = True) -> None:
+```
+Validates YAML file, throws if malformed or duplicate top-level keys are found.
+
+---
+
+### read_json_toml_yaml
+```python
+def read_json_toml_yaml(path_to_file: Path) -> Union[dict[str, Any], list[str]]:
+```
+Auto-detects file extension and deserializes JSON, TOML, or YAML to Python types.
+
+---
+
+## tinybear.txt
+
+### check_encoding_of_file
+```python
+def check_encoding_of_file(file: Path) -> str:
+```
+Check encoding (utf-8 or cp1251/ANSI); returns detected encoding.
+
+---
+
+### read_non_empty_lines_from_txt_file
+```python
+def read_non_empty_lines_from_txt_file(path_to_file: Path) -> list[str]:
+```
+Gets non-empty lines from TXT file as list.
+
+---
+
+### read_plain_text_from_file
+```python
+def read_plain_text_from_file(path_to_file: Path) -> str:
+```
+Reads plain text from file (utf-8 or cp1251 encoding).
+
+---
+
+### remove_extra_space
+```python
+def remove_extra_space(str_: str) -> str:
+```
+Removes leading/trailing/multiple spaces in a string.
+
+---
+
+### write_plain_text_to_file
+```python
+def write_plain_text_to_file(content: Union[str, list[str], tuple[str]], file: Path, overwrite: bool, newline_char: str = "\n") -> None:
+```
+Writes string or lines to text file. Optionally enforces overwrite/newlines.
+
+---
+
+### move_line
+```python
+def move_line(file: Path, line_number_to_cut: int, line_number_to_insert_before: Union[int, Literal["END"]], output_file: Union[Path, None] = None) -> None:
+```
+Moves a line in a text file to another position; saves to output file if given.
+
+---
+
+## tinybear.html.validate_html
+
+### validate_html
+```python
+def validate_html(html: str, allowed_tags: Iterable[str] = (...), is_text_at_root_level_allowed: bool = False) -> None:
+```
+Validate HTML string for allowed tags, structure, and correct entities. Raises ParsingError on errors.
+
+---
+
+## tinybear.html.from_docx
+
+### convert_file_from_doc
+```python
+def convert_file_from_doc(path_to_file: Path, output_dir: Path = DEFAULT_OUTPUT_DIR, style_map: str = DEFAULT_STYLE_MAP, print_html: bool = True) -> Path:
+```
+Read from DOC(x), write to HTML file, return output path.
+
+---
+
+### convert_all_docs
+```python
+def convert_all_docs(input_dir: Path = DEFAULT_INPUT_DIR, output_dir: Path = DEFAULT_OUTPUT_DIR, print_html: bool = True) -> None:
+```
+Convert all .DOC(x) files in a directory to HTML.
+
+---
+
+### read_from_doc
+```python
+def read_from_doc(path_to_file: Path, style_map: str = DEFAULT_STYLE_MAP) -> str:
+```
+Read binary DOCX file, return HTML string.
+
+---
+
+## tinybear.exceptions
+
+### ParsingError
+```python
+class ParsingError(Exception):
+    """Base class for all parsing errors."""
+```

docs/getting_started.md

@@ -0,0 +1,29 @@
+# Getting Started
+
+Welcome to **TinyBear**!
+
+This guide will help you quickly set up and start using TinyBear in your project.
+
+## Installation
+
+You can install TinyBear via pip:
+
+```bash
+pip install tinybear
+```
+
+Or clone the repository and install locally:
+
+```bash
+git clone https://github.com/lemontree210/tinybear
+cd tinybear
+pip install .
+```
+
+## Requirements
+
+TinyBear requires Python 3.9 or newer.
+
+---
+
+Continue to the [Usage](usage.md) section to learn how to use TinyBear in your workflow.

docs/index.md

@@ -0,0 +1,25 @@
+# TinyBear
+
+**TinyBear** is a lightweight utility library for working with data files and serialization formats in Python. It provides convenient tools for reading, writing, and validating CSV, XLS, JSON, TOML, YAML, and HTML files.
+
+---
+
+## Features
+
+- Simple interface for common data tasks
+- Support for multiple data formats
+- Easy data validation
+- Designed for Python 3.9+
+- Minimal dependencies
+
+---
+
+## Get Started
+
+- 📖 [Getting Started](getting_started.md)
+- ⚡ [Usage](usage.md)
+- 🧩 [API Reference](api.md)
+
+---
+
+For more details on available modules and methods, see the source code or contribute to extend the docs!

docs/usage.md

@@ -0,0 +1,33 @@
+# Usage
+
+This section provides examples and instructions for using TinyBear.
+
+## Importing Modules
+
+You can import TinyBear modules in your Python code:
+
+```python
+from tinybear import csv_xls, json_toml_yaml
+```
+
+## CSV/XLS Operations
+
+Read, write, and process CSV or XLS files using the `csv_xls` module. Example:
+
+```python
+from tinybear import csv_xls
+# usage example here
+```
+
+## JSON, TOML, YAML Handling
+
+Use the `json_toml_yaml` module for seamless serialization and deserialization:
+
+```python
+from tinybear import json_toml_yaml
+# usage example here
+```
+
+---
+
+For more detailed API information, refer to the source code or contribute to the docs!

mkdocs.yml

@@ -0,0 +1,22 @@
+site_name: TinyBear Documentation
+site_url: https://lemontree210.github.io/tinybear/
+extra:
+  base_url: /tinybear/
+nav:
+  - Home: index.md
+  - Getting Started: getting_started.md
+  - Usage: usage.md
+  - API Reference: api.md
+docs_dir: docs
+site_dir: site
+theme:
+  name: material
+  features:
+    - navigation.instant  # ⚡ Instant loading
+    - navigation.tracking  # 📊 Track scroll position
+    - navigation.tabs.sticky  # 📌 Sticky navigation
+    - navigation.top  # ⬆️ Back to top button
+    - search.suggest  # 🔍 Search suggestions
+    - search.share  # 🔗 Share search
+    - header.autohide  # 🎩 Auto-hide header
+    - content.code.annotate  # 💡 Code annotations