Update RST documentation for PR#10 multi-database and threading features

CHANGELOG.md

@@ -1,11 +1,19 @@
 # Changelog
 
-## Version 0.98rc1
+## Version 1.0rc1
 
-- Finish Documentation including Docstrings
-- Fix Metadata
+- **Multi-Database Support**: Added support for multiple database endpoints with automatic load balancing
+- **Threading Models**: Support for both threaded and non-threaded deployment scenarios  
+- **Improved Architecture**: Enhanced connection handling and pool management
+- **Documentation**: Complete rewrite of documentation to reflect new features
+- **API Improvements**: Better error handling and connection management
 
 ## Version 0.99
 
 - Add Handler.commit() procedure used for autocommit=False connections
 
+## Version 0.98rc1
+
+- Finish Documentation including Docstrings
+- Fix Metadata
+

doc/conf.py/source/api.rst

@@ -1,15 +1,70 @@
 .. api
 
-=============================
-Internal Class Representation 
-=============================
+=============
+API Reference
+=============
 
-pgdbpool
-========
+Complete API documentation for pgdbpool classes and functions.
+
+pgdbpool Module
+===============
+
+Core Classes
+------------
+
+.. automodule:: pgdbpool.pool
+   :members: Connection, Handler, Query
+   :special-members: __init__, __enter__, __exit__
+   :exclude-members: __weakref__
+   :show-inheritance:
+
+Utility Functions
+-----------------
+
+.. automodule:: pgdbpool.pool
+   :members: conn_iter
+   :exclude-members: __weakref__
+
+Exception Classes
+-----------------
 
 .. automodule:: pgdbpool.pool
-   :members: conn_iter, conn_iter_locked, Connection, Query, Handler
-   :special-members:
-   :private-members:
+   :members: DBConnectionError, DBQueryError, DBOfflineError, UnconfiguredGroupError
    :exclude-members: __weakref__
    :show-inheritance:
+
+Class Method Reference
+======================
+
+Connection Class Methods
+-------------------------
+
+The Connection class provides static methods for pool management:
+
+- **init(config)**: Initialize connection pool with configuration
+- **get_threading_model()**: Return current threading model ('threaded' or 'non-threaded')
+- **get_max_pool_size(group)**: Get maximum connections for a group
+- **get_next_connection(group)**: Get next available connection from group
+- **connect(connection)**: Establish database connection
+- **reconnect(connection)**: Reconnect failed database connection
+- **check_db(connection)**: Verify database connection health
+
+Handler Context Manager
+-----------------------
+
+The Handler class provides a context manager for database operations:
+
+- **__init__(group)**: Initialize handler for connection group
+- **__enter__()**: Enter context, acquire connection
+- **__exit__()**: Exit context, release connection
+- **query(statement, params=None)**: Execute SQL query
+- **query_prepared(params)**: Execute prepared statement  
+- **commit()**: Commit transaction (for autocommit=False groups)
+
+Query Static Methods
+--------------------
+
+The Query class provides static methods for SQL execution:
+
+- **execute(connection, sql_statement, sql_params=None)**: Execute SQL statement
+- **execute_prepared(connection, sql_params)**: Execute prepared statement

doc/conf.py/source/build.rst

@@ -1,47 +1,159 @@
 .. build
 
-============
-Build Module
-============
+=================
+Building pgdbpool
+=================
 
-1. Consider Using Environment
-=============================
+Guide for building pgdbpool from source code.
+
+1. Development Environment Setup
+================================
 
-Python PEP 405 proposes Virtual Environments. Think about using.
+**Virtual Environment (Recommended)**
 
-2. Clone Repository
-===================
+Python PEP 405 virtual environments provide isolated development environments:
+
+.. code-block:: bash
+
+    # create virtual environment
+    python3 -m venv pgdbpool-dev
+    source pgdbpool-dev/bin/activate  # Linux/macOS
+    # pgdbpool-dev\Scripts\activate   # Windows
+
+    # upgrade pip
+    pip install --upgrade pip
+
+2. Source Code Acquisition
+===========================
+
+**Clone from GitHub:**
 
 .. code-block:: bash
 
     git clone https://github.com/clauspruefer/python-dbpool.git
     cd python-dbpool
 
-3. Build As Non Root User
-=========================
+**Download Release Archive:**
+
+.. code-block:: bash
+
+    # download latest release
+    wget https://github.com/clauspruefer/python-dbpool/archive/refs/tags/v1.0rc1.tar.gz
+    tar -xzf v1.0rc1.tar.gz
+    cd python-dbpool-1.0rc1
+
+3. Install Dependencies
+=======================
+
+**Runtime Dependencies:**
+
+.. code-block:: bash
+
+    # install postgresql adapter
+    pip install psycopg2-binary
+    
+    # or compile from source (requires libpq-dev)
+    # apt-get install libpq-dev  # Debian/Ubuntu
+    # pip install psycopg2
+
+**Development Dependencies:**
+
+.. code-block:: bash
+
+    # install testing framework
+    pip install pytest pytest-cov
+    
+    # install documentation tools (optional)
+    pip install sphinx sphinx-rtd-theme
+
+4. Build Distribution Package
+=============================
+
+**Create Source Distribution:**
 
 .. code-block:: bash
 
-    python3 setup.py sdist
+    # modern way using build
+    pip install build
+    python -m build --sdist
 
-4. Install As Root User
+    # legacy way using setuptools
+    python setup.py sdist
+
+**Create Wheel Distribution:**
+
+.. code-block:: bash
+
+    python -m build --wheel
+
+5. Installation Methods
 =======================
 
+**Development Installation (Editable):**
+
 .. code-block:: bash
 
-    sudo pip3 install ./dist/package-0.1.tar.gz
+    # install in development mode
+    pip install -e .
 
-or global on restrictive PIP package manager systems ...
+**Local Package Installation:**
 
 .. code-block:: bash
 
-    sudo pip3 install ./dist/package-0.1.tar.gz --break-system-packages
+    # install from built package
+    pip install dist/pgdbpool-1.0rc1.tar.gz
 
-5. Run Tests
-============
+**System-wide Installation:**
 
-To ensure everything works correctly, run tests (after module installation).
+.. code-block:: bash
+
+    # install system-wide (requires sudo)
+    sudo pip install dist/pgdbpool-1.0rc1.tar.gz
+    
+    # for restrictive systems
+    sudo pip install dist/pgdbpool-1.0rc1.tar.gz --break-system-packages
+
+6. Testing
+==========
+
+**Run Test Suite:**
 
 .. code-block:: bash
 
+    # run all tests
     pytest
+    
+    # run with coverage report
+    pytest --cov=pgdbpool --cov-report=html
+    
+    # run specific test file
+    pytest test/unit/test_pool.py
+
+**Test Configuration:**
+
+Tests require a PostgreSQL database. Set environment variables:
+
+.. code-block:: bash
+
+    export PSQL_PWD="your_test_db_password"
+    export TEST_DB_HOST="localhost"
+    export TEST_DB_NAME="test_database"
+    export TEST_DB_USER="test_user"
+
+7. Documentation Building
+=========================
+
+**Build HTML Documentation:**
+
+.. code-block:: bash
+
+    cd doc/conf.py
+    sphinx-build -b html source build/html
+
+**View Documentation:**
+
+.. code-block:: bash
+
+    # open in browser
+    open build/html/index.html  # macOS
+    xdg-open build/html/index.html  # Linux