docs, jekyll, and fix a deprecation in black

Author: Antony Bailey

.github/workflows/python-package.yml

@@ -36,4 +36,6 @@ jobs:
         black --check .
     - name: Test with pytest
       run: |
+        # Make sure run_tests.sh is executable
+        chmod +x ./run_tests.sh
         ./run_tests.sh

API.md

@@ -1,6 +1,6 @@
 # pySQLY API Documentation
 
-This document provides detailed information about the pySQLY API.
+This document provides detailed information about the pySQLY API for developers working with the library.
 
 ## Table of Contents
 
@@ -39,7 +39,7 @@ SQLYExecutor(datasource, db_type=None)
 
 #### Methods
 
-##### execute
+##### execute_query
 
 ```python
 execute(query: str) -> Any
@@ -82,7 +82,7 @@ where:
 
 Handles parsing of SQLY query strings into structured dictionaries.
 
-#### Methods
+#### SQLYParser Methods
 
 ##### parse
 
@@ -122,7 +122,7 @@ parsed_query = SQLYParser.parse(query)
 
 Utility functions for SQLY operations.
 
-#### Methods
+#### SQLYUtils Methods
 
 ##### validate_query
 
@@ -194,7 +194,7 @@ Abstract method that must be implemented by all connectors.
 
 Base implementation of the IDBConnector interface.
 
-#### Methods
+#### BaseDBConnector Methods
 
 ##### execute_query
 
@@ -216,7 +216,7 @@ Executes raw SQL with parameters.
 
 High-level connector that manages connections to various database types.
 
-#### Constructor
+#### DatabaseConnector Constructor
 
 ```python
 DatabaseConnector(db_type, connection)
@@ -241,7 +241,7 @@ Executes a SQLY query against a specified database.
 
 Factory class for creating database-specific connectors.
 
-#### Methods
+#### DBConnectorFactory Methods
 
 ##### create_connector
 
@@ -325,4 +325,11 @@ optional arguments:
   --version             show program's version number and exit
 ```
 
-For more examples, see the [Examples](./EXAMPLES.md) document.
+## Related Resources
+
+- [Main README](./README.md) - Overview and getting started
+- [Examples](./EXAMPLES.md) - Usage examples and patterns
+- [Design Document](./DESIGN.md) - Architecture and design decisions
+- [Security Policy](./SECURITY.md) - Security considerations
+- [Changelog](./CHANGELOG.md) - Version history and changes
+- [Contributing](./CONTRIBUTING.md) - How to contribute to pySQLY

CONTRIBUTING.md

@@ -8,9 +8,11 @@ Thank you for your interest in contributing to pySQLY! This document provides gu
 - [Getting Started](#getting-started)
 - [Development Workflow](#development-workflow)
 - [Coding Standards](#coding-standards)
+- [Documentation](#documentation)
 - [Testing](#testing)
 - [Submitting Changes](#submitting-changes)
 - [Issue Reporting](#issue-reporting)
+- [Versioning](#versioning)
 
 ## Code of Conduct
 
@@ -38,14 +40,12 @@ This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md) that all contrib
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows, use: venv\Scripts\activate
-   pip install -e .  # Install in development mode
-   pip install -r requirements.txt
+   pip install -e ".[dev]"  # Install in development mode with development dependencies
    ```
 
 4. Set up pre-commit hooks:
 
    ```bash
-   pip install pre-commit
    pre-commit install
    ```
 
@@ -84,11 +84,26 @@ pySQLY follows these coding standards:
 
 These tools are configured in the project and run automatically with pre-commit hooks.
 
+### Running the Linters
+
+```bash
+# Format code with Black
+black src/ tests/
+
+# Sort imports with isort
+isort src/ tests/
+
+# Lint with Ruff
+ruff check src/ tests/
+```
+
 ## Documentation
 
 - Use docstrings for all public modules, functions, classes, and methods
 - Follow [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
 - Update documentation when changing functionality
+- Add examples for new features
+- Keep the [API Documentation](./API.md) up to date with any changes
 
 ## Testing
 
@@ -120,26 +135,47 @@ pytest --cov=pysqly
 
 3. In your PR description:
    - Clearly describe the problem and solution
-   - Include the relevant issue number if applicable
+   - Include the relevant issue number if applicable (e.g., "Fixes #123")
    - Mention if it changes external behavior
+   - Reference any related PRs or issues
+
+4. Wait for the maintainers to review your PR. They may ask for changes before merging.
 
 ## Issue Reporting
 
 - Use the GitHub issue tracker to report bugs or request features
+- Before submitting a new issue, check if it already exists
 - For bugs, include:
   - Steps to reproduce
   - Expected behavior
   - Actual behavior
   - Python and pySQLY versions
   - Operating system
   - Any relevant error messages or logs
+  - Minimal code example that reproduces the issue
+
+### Issue Templates
+
+When creating a new issue, choose the appropriate template:
+
+- Bug report: For reporting bugs or unexpected behavior
+- Feature request: For suggesting new features or improvements
+- Documentation issue: For reporting issues with documentation
 
 ## Versioning
 
 We use [Semantic Versioning](https://semver.org/) for version numbers:
 
-- MAJOR version for incompatible API changes
-- MINOR version for backward-compatible new features
-- PATCH version for backward-compatible bug fixes
+- MAJOR version for incompatible API changes (X.0.0)
+- MINOR version for backward-compatible new features (0.X.0)
+- PATCH version for backward-compatible bug fixes (0.0.X)
+
+## Related Resources
+
+- [README](./README.md) - Project overview
+- [Design Document](./DESIGN.md) - Architecture and design decisions
+- [Security Policy](./SECURITY.md) - Security guidelines
+- [Code of Conduct](./CODE_OF_CONDUCT.md) - Community standards
+- [Changelog](./CHANGELOG.md) - Version history
 
 Thank you for contributing to pySQLY!

EXAMPLES.md

@@ -1,6 +1,6 @@
 # pySQLY Examples
 
-This document provides examples of how to use pySQLY in various scenarios.
+This document provides practical examples of how to use pySQLY in various scenarios to simplify your database interactions.
 
 ## Table of Contents
 
@@ -9,6 +9,7 @@ This document provides examples of how to use pySQLY in various scenarios.
 - [Working with Different Databases](#working-with-different-databases)
 - [CLI Examples](#cli-examples)
 - [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
 
 ## Basic Queries
 
@@ -231,4 +232,50 @@ except SQLYExecutionError as e:
     # Handle the error appropriately
 ```
 
-For more detailed API information, see the [API Documentation](./API.md).
+## Best Practices
+
+### Connection Management
+
+For better performance, reuse executor instances when making multiple queries:
+
+```python
+# Create once, use many times
+executor = SQLYExecutor("database.db", "sqlite")
+
+# Query 1
+users = executor.execute(user_query)
+
+# Query 2
+products = executor.execute(product_query)
+```
+
+### Error Handling Strategy
+
+Implement a comprehensive error handling strategy:
+
+```python
+from pysqly import SQLYExecutor, SQLYParseError, SQLYExecutionError, SQLYError
+
+try:
+    executor = SQLYExecutor("database.db", "sqlite")
+    results = executor.execute(query)
+except SQLYParseError as e:
+    # Handle parsing errors specifically
+    logger.error(f"Invalid YAML syntax: {e}")
+except SQLYExecutionError as e:
+    # Handle execution errors specifically
+    logger.error(f"Database execution failed: {e}")
+except SQLYError as e:
+    # Handle any other pySQLY errors
+    logger.error(f"pySQLY error: {e}")
+except Exception as e:
+    # Handle unexpected errors
+    logger.critical(f"Unexpected error: {e}")
+```
+
+## Related Resources
+
+- [API Documentation](./API.md) - Detailed library API reference
+- [Design Document](./DESIGN.md) - Architecture and design patterns
+- [Security Policy](./SECURITY.md) - Security best practices
+- [Contributing](./CONTRIBUTING.md) - How to contribute to pySQLY

MANIFEST.in

@@ -3,9 +3,12 @@ include README.md
 include CHANGELOG.md
 include CONTRIBUTING.md
 include CODE_OF_CONDUCT.md
+include SECURITY.md
+include DESIGN.md
 include API.md
 include EXAMPLES.md
 include pyproject.toml
 include requirements.txt
+include run_tests.sh
 
 recursive-include tests *.py

README.md

@@ -95,6 +95,9 @@ sqly-cli "select: [username, email]\nfrom: users\nwhere:\n  - field: active\n
 - [API Documentation](./API.md) - Detailed library API reference
 - [Examples](./EXAMPLES.md) - More usage examples and patterns
 - [Contributing](./CONTRIBUTING.md) - Guidelines for contributing to pySQLY
+- [Code of Conduct](./CODE_OF_CONDUCT.md) - Our community standards
+- [Security Policy](./SECURITY.md) - Reporting vulnerabilities and security practices
+- [Design Document](./DESIGN.md) - Architecture and design patterns
 - [Changelog](./CHANGELOG.md) - Version history and changes
 
 ## Project Structure
@@ -141,6 +144,8 @@ pySQLY/
 ├── EXAMPLES.md               # Usage examples
 ├── CONTRIBUTING.md           # Contribution guidelines
 ├── CODE_OF_CONDUCT.md        # Code of conduct
+├── SECURITY.md               # Security policy
+├── DESIGN.md                 # Architecture design
 └── CHANGELOG.md              # Version history
 ```
 
@@ -162,6 +167,14 @@ where:
 
 See the [Examples](./EXAMPLES.md) document for more complex query patterns.
 
+## Why Choose pySQLY?
+
+- **Simplified Database Access**: Write database queries in a more readable format
+- **Database Agnostic**: Switch between database systems without changing your query syntax
+- **Reduced SQL Injection Risk**: Parameter binding is handled automatically
+- **Improved Productivity**: Less boilerplate code and more intuitive query structure
+- **Easy Integration**: Works with your existing Python applications
+
 ## License
 
 pySQLY is distributed under the [MIT License](LICENSE).

_config.yml

@@ -2,13 +2,25 @@ remote_theme: pages-themes/architect@v0.2.0
 plugins:
 - jekyll-remote-theme
 - jekyll-seo-tag
+- jekyll-sitemap
 
 # Site settings
 title: Python Standard Query Language (pySQLY) Documentation
-description: A powerful Python library for standardized SQL querying
+description: "A powerful Python library for standardized SQL querying with YAML syntax - simplify database interactions across SQLite, MySQL, PostgreSQL, Oracle and MS SQL Server"
+author: Standard Query Language
+lang: en_US
 show_downloads: true
 google_analytics: # Add your GA tracking ID here if needed
 
+# SEO settings
+twitter:
+  username: pysqly
+  card: summary
+social:
+  name: pySQLY
+  links:
+    - https://github.com/Standard-Query-Language/pySQLY
+
 # Theme customization
 colors:
   header: "#2E7BCF"
@@ -23,6 +35,8 @@ nav:
     url: /
   - title: Documentation
     url: /docs/
+  - title: API Reference
+    url: /api/
   - title: Examples
     url: /examples/
   - title: GitHub

pyproject.toml

@@ -63,6 +63,8 @@ multi_line_output = 3
 
 [tool.ruff]
 line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
 select = ["E", "F", "I", "N", "B", "W"]
 ignore = ["E203"]
-target-version = "py39"