diff --git a/docs/templates/module-doc-rules.md b/docs/templates/module-doc-rules.md new file mode 100644 index 0000000..a957769 --- /dev/null +++ b/docs/templates/module-doc-rules.md @@ -0,0 +1,123 @@ +# 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 +``` diff --git a/docs/templates/module-doc-template.md b/docs/templates/module-doc-template.md new file mode 100644 index 0000000..08776a5 --- /dev/null +++ b/docs/templates/module-doc-template.md @@ -0,0 +1,108 @@ +# {{module_name}} Documentation + + +--- + +## Overview +{{module_name}} is a module/service that provides the following functionality: + +- Purpose: {{brief purpose description}} +- Primary Use Cases: {{key scenarios}} + +--- + +## Installation + +{{installation_steps}} + + +AI PROMPT GUIDELINE: +- Only modify the installation instructions here. +- Include version-specific steps if relevant. +- Add notes about dependencies. +- Keep commands formatted in code blocks. + +--- + +## Configuration + +{{configuration_details}} + + +AI PROMPT GUIDELINE: +- Only update configuration options. +- Include default values and examples. +- Do not remove existing valid options. +- Highlight optional vs required parameters. + +--- + +## Connections to other services, systems, and modules + +{{connections_list_and_description}} + + +AI PROMPT GUIDELINE: +- List all connection that are made to other services, systems, and modules. Where does this module sit in the stack? + +--- + +## Usage Examples + +{{usage_examples}} + + +AI PROMPT GUIDELINE: +- Add practical examples, commands, or API snippets. +- Format code blocks correctly. +- If updating, append new examples; never rewrite old ones unless flagged. + +--- + +## Dependencies + +{{dependencies_list}} + + +AI PROMPT GUIDELINE: +- List all libraries, modules, or services required. +- Include version constraints if applicable. +- Append new dependencies rather than replacing the list. +- Have credentials been added to Infisical? +- Is there a Web UI that needs to be configured? + +--- + +## Troubleshooting + +{{troubleshooting_tips}} + + +AI PROMPT GUIDELINE: +- Add solutions to common issues encountered during installation, configuration, or usage. +- Preserve existing tips. +- Add new tips with date stamps. + +--- + +## Change Log + +{{change_log}} + + +AI PROMPT GUIDELINE: +- Always append a new entry with: + - Date (YYYY-MM-DD) + - Type (Added / Updated / Fixed) + - Summary of changes +- Do not remove previous entries. + +--- + +## References +- [Official Module Repo]({{repo_url}}) +- [Related Documentation]({{related_docs_url}})