124 lines
4.0 KiB
Markdown
124 lines
4.0 KiB
Markdown
# Module Documentation — AI Writing Rules
|
|
|
|
Rules Grace follows when creating or updating any module doc using `module-doc-template.md`.
|
|
|
|
---
|
|
|
|
## General Rules
|
|
|
|
1. Do not delete any existing content unless explicitly instructed. Prefer appending or updating.
|
|
2. Preserve all formatting: Markdown headings, code blocks, bullets, spacing.
|
|
3. Additions must match the existing style and formatting in the file.
|
|
4. Return only the updated section(s) with AI GENERATED markers — not the full file — unless the full file is explicitly requested.
|
|
|
|
---
|
|
|
|
## Section-Specific Rules
|
|
|
|
### Overview
|
|
Describe what the module does, its purpose, and primary use cases.
|
|
|
|
### Installation
|
|
Add installation steps, version notes, or dependency instructions. Format all commands in code blocks.
|
|
|
|
### Configuration
|
|
Update or add configuration options with defaults and examples. Mark optional vs required parameters clearly.
|
|
|
|
### Connections to other services, systems, and modules
|
|
List ALL connections made to other services, systems, and modules. Describe where this module sits in the stack.
|
|
|
|
### Usage Examples
|
|
Add practical code snippets or commands. Append new examples — never remove old ones.
|
|
|
|
### Dependencies
|
|
Add required libraries/modules with version constraints. Append only. Always check:
|
|
- Have credentials been added to Infisical?
|
|
- Is there a Web UI that needs to be configured?
|
|
|
|
### Troubleshooting
|
|
Add solutions to common issues. Preserve existing tips. Include date stamps on new items.
|
|
|
|
### Change Log
|
|
Append entries in the format:
|
|
```
|
|
YYYY-MM-DD | Added/Updated/Fixed | Summary of changes
|
|
```
|
|
Never remove previous entries.
|
|
|
|
### References
|
|
Link to official docs, repos, and related internal docs. Flag external docs with:
|
|
```
|
|
AI TODO: Schedule RAG import for future reference.
|
|
```
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Overview Example
|
|
```
|
|
The {{module_name}} service provides secure handling of sensitive configuration data using
|
|
Infisical for secret management. It abstracts access to API keys, database credentials,
|
|
and environment variables, making deployment and scaling more secure and consistent.
|
|
|
|
Primary Use Cases:
|
|
- Automated retrieval of secrets at runtime
|
|
- Centralized configuration for microservices
|
|
- Integration with CI/CD pipelines for secure deployments
|
|
```
|
|
|
|
### Installation Example
|
|
```bash
|
|
pip install {{module_name}}=={{version}}
|
|
|
|
# Ensure the Infisical CLI is installed and authenticated:
|
|
curl -sL https://app.infisical.com/cli/install.sh | bash
|
|
infisical login --token $INFISICAL_TOKEN
|
|
|
|
# Verify installation:
|
|
python -c "import {{module_name}}; print({{module_name}}.__version__)"
|
|
|
|
# Optional: Install additional adapters if using PostgreSQL or Redis:
|
|
pip install {{module_name}}[postgres,redis]
|
|
```
|
|
|
|
### Configuration Example
|
|
```yaml
|
|
# Required configuration (fetched via Infisical)
|
|
SECRETS_PROJECT: my_project
|
|
SECRETS_ENV: production
|
|
|
|
# Optional configuration
|
|
ENABLE_LOGGING: false # Default false
|
|
CACHE_EXPIRY: 3600 # In seconds, default 1 hour
|
|
|
|
# Advanced options
|
|
RETRY_POLICY: exponential_backoff
|
|
RETRY_ATTEMPTS: 5
|
|
```
|
|
|
|
### Connections Example
|
|
```
|
|
- PostgreSQL database: Automatically retrieves DB_USER and DB_PASSWORD from Infisical.
|
|
- Redis cache: Optional caching layer, configured via CACHE_URL.
|
|
- CI/CD pipelines: Integrates with GitHub Actions or GitLab CI for secret injection.
|
|
- Microservices: Exposes a gRPC API for internal service communication.
|
|
|
|
AI TODO: Schedule RAG import for each external system's documentation for future reference.
|
|
```
|
|
|
|
### Troubleshooting Example
|
|
```
|
|
- Cannot retrieve secrets: Ensure INFISICAL_TOKEN is valid and CLI is logged in.
|
|
- Module fails to import: Verify Python version >= 3.11 and dependencies are installed.
|
|
- Cache not updating: Check CACHE_URL and network connectivity.
|
|
- Retries failing: Verify RETRY_POLICY settings; default is exponential_backoff.
|
|
- Secrets missing in production: Confirm project and environment settings in Infisical.
|
|
```
|
|
|
|
### Change Log Example
|
|
```
|
|
2026-03-17 | Added | Initial draft of module documentation with Infisical integration
|
|
2026-03-18 | Updated | Added optional caching layer and retry policy
|
|
```
|