kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Detailed Docs & Onboarding improvements

Browse Source
This commit is contained in:
ajaysi
2025-04-21 16:34:18 +05:30
parent 6e60a9fd28
commit c5b47bd32f
42 changed files with 5114 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
docs/developer/coding_standards.rst Normal file
View File

@@ -0,0 +1,230 @@
Coding Standards
===============
This document outlines the coding standards and best practices for contributing to the AI-Writer project.
Code Style
---------
AI-Writer follows the PEP 8 style guide for Python code with some additional guidelines:
1. **Indentation**
* Use 4 spaces for indentation (no tabs)
* Continuation lines should align with the opening delimiter or be indented by 4 spaces
2. **Line Length**
* Maximum line length is 100 characters
* For docstrings and comments, limit to 80 characters
3. **Imports**
* Group imports in the following order:
1. Standard library imports
2. Related third-party imports
3. Local application/library specific imports
* Within each group, imports should be sorted alphabetically
* Use absolute imports rather than relative imports
Example:
.. code-block:: python
# Standard library
import os
import sys
from typing import Dict, List, Optional
# Third-party
import numpy as np
import pandas as pd
import streamlit as st
# Local
from lib.database import models
from lib.utils import helpers
4. **Naming Conventions**
* Classes: `CamelCase`
* Functions and variables: `snake_case`
* Constants: `UPPER_CASE`
* Private methods and variables: `_leading_underscore`
* Protected methods and variables: `__double_leading_underscore`
5. **String Formatting**
* Use f-strings for string formatting when possible
* For older Python versions, use `.format()` method
* Avoid using `%` formatting
Example:
.. code-block:: python
# Preferred
name = "World"
greeting = f"Hello, {name}!"
# Acceptable
greeting = "Hello, {}!".format(name)
# Avoid
greeting = "Hello, %s!" % name
Documentation
------------
1. **Docstrings**
* Use Google-style docstrings
* All modules, classes, and functions should have docstrings
* Include type hints in function signatures
Example:
.. code-block:: python
def generate_content(prompt: str, max_tokens: int = 100) -> str:
"""Generate content using the AI model.
Args:
prompt: The input prompt for content generation.
max_tokens: Maximum number of tokens to generate.
Returns:
The generated content as a string.
Raises:
ValueError: If the prompt is empty or max_tokens is negative.
"""
if not prompt:
raise ValueError("Prompt cannot be empty")
if max_tokens < 0:
raise ValueError("max_tokens must be a positive integer")
# Implementation...
return generated_content
2. **Comments**
* Use comments sparingly and only when necessary
* Focus on explaining "why" rather than "what"
* Keep comments up-to-date with code changes
3. **Type Hints**
* Use type hints for all function parameters and return values
* Use `Optional` for parameters that can be None
* Use `Union` for parameters that can be multiple types
* Use `Any` only when absolutely necessary
Example:
.. code-block:: python
from typing import Dict, List, Optional, Union
def process_data(
data: Union[Dict[str, str], List[str]],
config: Optional[Dict[str, str]] = None
) -> List[str]:
"""Process the input data."""
# Implementation...
return processed_data
Error Handling
-------------
1. **Exceptions**
* Use specific exception types rather than generic exceptions
* Handle exceptions at the appropriate level
* Include meaningful error messages
* Log exceptions with appropriate context
Example:
.. code-block:: python
try:
result = api_client.fetch_data(query)
except ConnectionError as e:
logger.error(f"Failed to connect to API: {e}")
raise ServiceUnavailableError("API service is currently unavailable") from e
except ValueError as e:
logger.warning(f"Invalid query parameter: {e}")
raise InvalidParameterError(f"Invalid query parameter: {e}") from e
2. **Validation**
* Validate input parameters early
* Use assertions for internal checks (not for input validation)
* Return meaningful error messages for invalid inputs
Testing
------
1. **Test Coverage**
* Aim for at least 80% test coverage for new code
* Write unit tests for all new functions and classes
* Include integration tests for complex interactions
2. **Test Organization**
* Place tests in the `tests/` directory
* Mirror the package structure in the test directory
* Name test files with `test_` prefix
3. **Test Naming**
* Use descriptive test names that explain what is being tested
* Follow the pattern `test_<function_name>_<scenario>_<expected_result>`
Example:
.. code-block:: python
def test_generate_content_empty_prompt_raises_value_error():
"""Test that generate_content raises ValueError for empty prompts."""
with pytest.raises(ValueError, match="Prompt cannot be empty"):
generate_content("")
Performance Considerations
------------------------
1. **Resource Usage**
* Be mindful of memory usage, especially for large datasets
* Use generators and iterators for large data processing
* Consider using async functions for I/O-bound operations
2. **Optimization**
* Optimize for readability first, then performance
* Document performance-critical sections
* Include benchmarks for performance-sensitive code
Security Best Practices
---------------------
1. **API Keys and Secrets**
* Never hardcode API keys or secrets
* Use environment variables or secure storage
* Implement proper access controls for sensitive data
2. **Input Validation**
* Validate and sanitize all user inputs
* Use parameterized queries for database operations
* Implement proper authentication and authorization
3. **Dependency Management**
* Keep dependencies up-to-date
* Regularly check for security vulnerabilities
* Pin dependency versions for reproducibility

39
docs/developer/index.rst Normal file
View File

@@ -0,0 +1,39 @@
Developer Guide
==============
This section provides comprehensive documentation for developers who want to contribute to or extend the AI-Writer platform.
.. toctree::
:maxdepth: 2
:caption: Developer Documentation:
setup
architecture
coding_standards
testing
extending
Development Environment Setup
---------------------------
.. include:: setup.rst
Architecture Overview
-------------------
.. include:: architecture.rst
Coding Standards
--------------
.. include:: coding_standards.rst
Testing Guidelines
----------------
.. include:: testing.rst
Extending AI-Writer
-----------------
.. include:: extending.rst

176
docs/developer/setup.rst Normal file
View File

@@ -0,0 +1,176 @@
Development Environment Setup
============================
This guide will help you set up a development environment for contributing to the AI-Writer project.
Prerequisites
------------
Before setting up the development environment, ensure you have the following installed:
* Python 3.9 or higher
* Git
* A code editor (VS Code, PyCharm, etc.)
* Docker (optional, for containerized development)
Setting Up the Development Environment
------------------------------------
1. **Clone the Repository**
.. code-block:: bash
git clone https://github.com/AJaySi/AI-Writer.git
cd AI-Writer
2. **Create a Virtual Environment**
.. code-block:: bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
3. **Install Development Dependencies**
.. code-block:: bash
pip install -r requirements.txt
pip install -r requirements-dev.txt # Install development dependencies
4. **Set Up Pre-commit Hooks**
.. code-block:: bash
pip install pre-commit
pre-commit install
5. **Configure Environment Variables**
Create a `.env` file in the project root with the following variables:
.. code-block:: bash
# API Keys
OPENAI_API_KEY=your_openai_api_key
GOOGLE_API_KEY=your_google_api_key
# Database Configuration
DB_PATH=sqlite:///./data/alwrity.db
VECTOR_DB_PATH=./data/vectordb
# Development Settings
DEBUG=True
ENVIRONMENT=development
6. **Initialize the Database**
.. code-block:: bash
python -c "from lib.database.db_manager import init_db; init_db()"
7. **Run the Development Server**
.. code-block:: bash
streamlit run alwrity.py
Development Workflow
------------------
1. **Create a Feature Branch**
Always create a new branch for your changes:
.. code-block:: bash
git checkout -b feature/your-feature-name
2. **Make Changes and Test**
Implement your changes and test them thoroughly:
.. code-block:: bash
# Run tests
pytest
# Run linting
flake8
# Run type checking
mypy .
3. **Commit Changes**
Follow the commit message conventions:
.. code-block:: bash
git add .
git commit -m "feat: add new feature"
4. **Push Changes and Create a Pull Request**
.. code-block:: bash
git push origin feature/your-feature-name
Then create a pull request on GitHub.
Using Docker for Development
--------------------------
For containerized development:
1. **Build the Development Container**
.. code-block:: bash
docker build -t alwrity-dev -f Dockerfile.dev .
2. **Run the Development Container**
.. code-block:: bash
docker run -p 8501:8501 -v $(pwd):/app alwrity-dev
3. **Using Docker Compose**
.. code-block:: bash
docker-compose -f docker-compose.dev.yml up
Troubleshooting
-------------
Common development setup issues:
1. **Dependency Conflicts**
If you encounter dependency conflicts, try:
.. code-block:: bash
pip install --upgrade pip
pip install -r requirements.txt --no-cache-dir
2. **Database Migration Issues**
If you encounter database migration issues:
.. code-block:: bash
# Reset the database
rm -rf ./data/alwrity.db
rm -rf ./data/vectordb
# Reinitialize
python -c "from lib.database.db_manager import init_db; init_db()"
3. **Streamlit Port Already in Use**
If the Streamlit port is already in use:
.. code-block:: bash
streamlit run alwrity.py --server.port=8502