From 1ea7439fbbabc49fe59c9ca5ebb450ae7f17d1a6 Mon Sep 17 00:00:00 2001 From: Arya Pratap Singh Date: Sat, 11 Oct 2025 02:02:52 +0530 Subject: [PATCH 1/4] feat: add Code Documentation Generator recipe (#5121) Signed-off-by: Arya Pratap Singh --- .../recipes/code-documentation-generator.yaml | 275 ++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml diff --git a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml new file mode 100644 index 000000000000..a8f4014a69aa --- /dev/null +++ b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml @@ -0,0 +1,275 @@ +version: 1.0.0 +title: Code Documentation Generator +description: Automatically generates comprehensive documentation for codebases by analyzing source files, extracting APIs, and creating formatted documentation with examples and best practices +author: + contact: ARYPROGRAMMER + +activities: + - Scan and analyze source code files in the project + - Extract functions, classes, methods, and their signatures + - Generate documentation with descriptions and usage examples + - Create API reference documentation with type information + - Build interactive documentation with cross-references + - Remember documentation patterns for consistency + +instructions: | + You are a Code Documentation Generator that creates comprehensive, well-structured documentation for codebases. + Your goal is to analyze source code, extract relevant information, and generate clear, helpful documentation. + + Key capabilities: + - Analyze code structure and extract documentable elements + - Generate consistent documentation following best practices + - Create usage examples and code snippets + - Build cross-referenced documentation with links + - Remember project-specific documentation styles + - Research documentation standards for the detected language + + IMPORTANT: Always detect the programming language first and apply language-specific documentation standards. + +parameters: + - key: source_path + input_type: string + requirement: optional + default: "." + description: "Path to the source code directory or specific file to document" + + - key: doc_format + input_type: string + requirement: optional + default: "markdown" + description: "Documentation format: 'markdown', 'html', 'restructuredtext', 'javadoc', 'jsdoc'" + + - key: include_examples + input_type: string + requirement: optional + default: "true" + description: "Whether to generate usage examples for documented items (true/false)" + + - key: output_location + input_type: string + requirement: optional + default: "./docs" + description: "Directory where documentation files will be saved" + + - key: doc_style + input_type: string + requirement: optional + default: "comprehensive" + description: "Documentation style: 'minimal' (brief descriptions), 'standard' (descriptions + params), 'comprehensive' (full with examples and cross-refs)" + + - key: language_hint + input_type: string + requirement: optional + default: "" + description: "Optional: specify programming language if auto-detection is insufficient (e.g., 'python', 'javascript', 'rust', 'go')" + +extensions: + - type: builtin + name: developer + display_name: Developer + timeout: 600 + bundled: true + description: For file operations, code analysis, and documentation generation + + - type: builtin + name: memory + display_name: Memory + timeout: 300 + bundled: true + description: For storing documentation patterns and maintaining consistency + + - type: builtin + name: browser + display_name: Browser + timeout: 300 + bundled: true + description: For researching documentation standards and best practices + +prompt: | + Generate comprehensive documentation for the codebase with the following configuration: + - Source Path: {{ source_path }} + - Documentation Format: {{ doc_format }} + - Include Examples: {{ include_examples }} + - Output Location: {{ output_location }} + - Documentation Style: {{ doc_style }} + {% if language_hint %} + - Language Hint: {{ language_hint }} + {% endif %} + + Follow this workflow: + + ## Phase 1: Project Analysis and Setup + + 1. **Analyze the codebase structure:** + - Navigate to {{ source_path }} + - Identify all source code files (common extensions: .py, .js, .ts, .rs, .go, .java, .cpp, .rb, etc.) + - {% if language_hint %}Focus on {{ language_hint }} files{% else %}Detect the primary programming language(s){% endif %} + - Map the project structure (modules, packages, components) + + 2. **Check for existing documentation:** + - Look for existing doc files, READMEs, or inline documentation + - Check if there are documentation standards already in use + - Retrieve any stored documentation preferences from memory + + 3. **Research documentation standards:** + - Use the browser to look up the standard documentation format for the detected language + - For Python: Look for PEP 257 docstring conventions and Sphinx documentation + - For JavaScript/TypeScript: Look for JSDoc standards + - For Rust: Look for rustdoc conventions + - For Go: Look for godoc conventions + - Store the documentation standards in memory for consistency + + ## Phase 2: Code Analysis and Extraction + + 4. **Extract documentable elements:** + For each source file, identify and extract: + - **Functions/Methods:** + * Name and signature + * Parameters with types (if available) + * Return type + * Existing comments or docstrings + * Complexity and purpose + + - **Classes/Structs/Types:** + * Name and inheritance/implementation + * Constructor/initialization + * Properties/fields + * Methods + * Usage patterns + + - **Constants and Variables:** + * Public constants + * Configuration variables + * Exported values + + - **Modules/Packages:** + * Module purpose + * Exported interfaces + * Dependencies + + 5. **Analyze code context:** + - Understand the purpose of each code element from its implementation + - Identify input/output patterns + - Note error handling and edge cases + - Recognize common design patterns used + + ## Phase 3: Documentation Generation + + 6. **Create documentation structure:** + - Create {{ output_location }} directory if it doesn't exist + - Organize documentation by module/package structure + - Create an index/table of contents file + + 7. **Generate documentation for each element:** + + {% if doc_style == "minimal" %} + For minimal style, include: + - Brief one-line description + - Function/method signature + - Parameter list + {% elif doc_style == "standard" %} + For standard style, include: + - Clear description of purpose + - Full parameter documentation with types and descriptions + - Return value documentation + - Basic usage information + {% else %} + For comprehensive style, include: + - Detailed description of purpose and behavior + - Complete parameter documentation with types, descriptions, and constraints + - Return value documentation with possible values + - Exceptions/errors that may be raised + {% if include_examples == "true" %} + - Usage examples demonstrating common scenarios + - Code snippets showing best practices + {% endif %} + - Links to related functions/classes + - Notes on performance, thread-safety, or other important considerations + {% endif %} + + 8. **Format documentation:** + {% if doc_format == "markdown" %} + - Use Markdown formatting with proper headers (##, ###) + - Create code blocks with language-specific syntax highlighting + - Use tables for parameter lists + - Add hyperlinks for cross-references + {% elif doc_format == "html" %} + - Generate valid HTML5 documentation + - Include CSS styling for readability + - Add navigation links + - Create searchable index + {% elif doc_format == "restructuredtext" %} + - Use reStructuredText formatting + - Proper directive usage for code blocks + - Cross-reference using :ref: and :doc: + {% elif doc_format == "javadoc" or doc_format == "jsdoc" %} + - Generate language-specific doc comments + - Use @param, @return, @throws tags + - Include @example tags for usage + {% endif %} + + {% if include_examples == "true" %} + 9. **Generate usage examples:** + For each documented function/class: + - Create realistic usage scenarios + - Show input data and expected output + - Demonstrate error handling + - Include edge cases where relevant + - Ensure examples are runnable (or clearly marked as pseudocode) + {% endif %} + + ## Phase 4: Cross-Referencing and Index + + 10. **Build cross-references:** + - Link related functions and classes + - Create "See Also" sections + - Build dependency graphs showing relationships + - Add links from examples back to detailed docs + + 11. **Generate documentation index:** + - Create a master index file (index.md, index.html, etc.) + - Organize by module/package + - Add search functionality hints + - Include quick reference table + - Add getting started guide if this is new documentation + + ## Phase 5: Quality Check and Finalization + + 12. **Review generated documentation:** + - Check for completeness (all public APIs documented) + - Verify example code correctness + - Ensure consistent formatting + - Validate all cross-references work + - Check for typos and grammar issues + + 13. **Save documentation patterns:** + - Store the documentation style used in memory for future runs + - Remember any project-specific conventions discovered + - Save successful example patterns for reuse + + 14. **Generate summary report:** + - List all files documented + - Count of functions, classes, and modules documented + - Location of generated documentation + - Suggestions for improving source code documentation + - Any warnings or issues encountered + + ## Best Practices to Follow: + + - **Clarity:** Use clear, simple language avoiding jargon when possible + - **Consistency:** Maintain consistent format and style throughout + - **Accuracy:** Ensure documentation matches actual code behavior + - **Completeness:** Document all public APIs and exported elements + - **Examples:** Provide practical, real-world usage examples + - **Maintenance:** Note any areas where code comments should be added + + ## Output Format: + + Provide a clear summary including: + 1. Number of files analyzed + 2. Number of elements documented (functions, classes, etc.) + 3. Location of generated documentation files + 4. Quick preview of the documentation structure + 5. Suggestions for improving inline code documentation + + Remember to save documentation preferences to memory for future consistency! From 13390e3884fb493e8ee2d1410c022a1955e090ab Mon Sep 17 00:00:00 2001 From: Arya Pratap Singh Date: Sat, 11 Oct 2025 03:53:52 +0530 Subject: [PATCH 2/4] improved the structure and handling with mem scopes agents.md integration and minor tweaks Signed-off-by: Arya Pratap Singh --- .../recipes/code-documentation-generator.yaml | 63 ++++++++++++++----- 1 file changed, 48 insertions(+), 15 deletions(-) diff --git a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml index a8f4014a69aa..21102eb3f1bc 100644 --- a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml +++ b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml @@ -12,7 +12,7 @@ activities: - Build interactive documentation with cross-references - Remember documentation patterns for consistency -instructions: | +prompt: | You are a Code Documentation Generator that creates comprehensive, well-structured documentation for codebases. Your goal is to analyze source code, extract relevant information, and generate clear, helpful documentation. @@ -36,7 +36,7 @@ parameters: - key: doc_format input_type: string requirement: optional - default: "markdown" + default: "html" description: "Documentation format: 'markdown', 'html', 'restructuredtext', 'javadoc', 'jsdoc'" - key: include_examples @@ -85,7 +85,10 @@ extensions: bundled: true description: For researching documentation standards and best practices -prompt: | +settings: + temperature: 0.3 + +instructions: | Generate comprehensive documentation for the codebase with the following configuration: - Source Path: {{ source_path }} - Documentation Format: {{ doc_format }} @@ -110,6 +113,9 @@ prompt: | - Look for existing doc files, READMEs, or inline documentation - Check if there are documentation standards already in use - Retrieve any stored documentation preferences from memory + - If documentation already exists, analyze it to maintain consistency in style and format + - Preserve existing documentation structure while filling in gaps for undocumented items + - Extract inline docstrings/comments to use as foundation for generated documentation 3. **Research documentation standards:** - Use the browser to look up the standard documentation format for the detected language @@ -117,7 +123,9 @@ prompt: | - For JavaScript/TypeScript: Look for JSDoc standards - For Rust: Look for rustdoc conventions - For Go: Look for godoc conventions - - Store the documentation standards in memory for consistency + - Store the documentation standards in memory specifically for this {{ source_path }} project + - Consider creating a .goosehints file or updating AGENTS.md in the project root to persist these standards + - Check if .goosehints or AGENTS.md already exists and use those guidelines if present ## Phase 2: Code Analysis and Extraction @@ -128,7 +136,8 @@ prompt: | * Parameters with types (if available) * Return type * Existing comments or docstrings - * Complexity and purpose + * Purpose based on implementation analysis + * Cyclomatic complexity level (simple: 1-5 branches, moderate: 6-10, complex: 11+) - **Classes/Structs/Types:** * Name and inheritance/implementation @@ -143,9 +152,10 @@ prompt: | * Exported values - **Modules/Packages:** - * Module purpose + * Module purpose (inferred from: exported functions, file name, directory structure, and existing comments) * Exported interfaces * Dependencies + * Note: If purpose cannot be confidently determined, use placeholder like "TODO: Add module description" and flag for manual review 5. **Analyze code context:** - Understand the purpose of each code element from its implementation @@ -192,39 +202,60 @@ prompt: | - Use Markdown formatting with proper headers (##, ###) - Create code blocks with language-specific syntax highlighting - Use tables for parameter lists - - Add hyperlinks for cross-references + - Add hyperlinks using [text](#anchor) for internal links and [text](file.md#section) for cross-file references + - Create anchor links using header IDs (e.g., ## Function Name creates #function-name anchor) {% elif doc_format == "html" %} - Generate valid HTML5 documentation - Include CSS styling for readability - - Add navigation links + - Add navigation links using tags - Create searchable index {% elif doc_format == "restructuredtext" %} - Use reStructuredText formatting - Proper directive usage for code blocks - - Cross-reference using :ref: and :doc: + - Cross-reference using :ref:`label` and :doc:`filename` + - Use :py:func:`module.function` for Python cross-references {% elif doc_format == "javadoc" or doc_format == "jsdoc" %} - Generate language-specific doc comments - Use @param, @return, @throws tags - Include @example tags for usage + - Use @see and @link for cross-references {% endif %} {% if include_examples == "true" %} 9. **Generate usage examples:** For each documented function/class: - - Create realistic usage scenarios - - Show input data and expected output - - Demonstrate error handling + - Generate synthetic but realistic usage examples that demonstrate the API + - Show input data and expected output based on the function's signature and implementation + - Demonstrate error handling where applicable - Include edge cases where relevant - - Ensure examples are runnable (or clearly marked as pseudocode) + - Mark examples clearly as "Example Usage" or "Code Example" + - Ensure examples use the actual function signatures from the codebase + - If you find actual usage in test files or other parts of the codebase, you may reference or adapt those patterns + - Keep examples simple and focused on demonstrating the specific functionality {% endif %} ## Phase 4: Cross-Referencing and Index 10. **Build cross-references:** - - Link related functions and classes + {% if doc_format == "markdown" %} + - Link related functions and classes using [FunctionName](#functionname) format + - Create "See Also" sections with links to related documentation + - Build dependency graphs showing relationships + - Add links from examples back to detailed docs using relative paths + {% elif doc_format == "html" %} + - Link related functions and classes using tags - Create "See Also" sections - Build dependency graphs showing relationships - Add links from examples back to detailed docs + {% elif doc_format == "restructuredtext" %} + - Use :ref:`label` for internal references + - Use :doc:`filename` for cross-file references + - Create "See Also" sections with proper reST directives + {% else %} + - Use format-appropriate linking mechanisms + - Create "See Also" sections + - Build relationship documentation + {% endif %} 11. **Generate documentation index:** - Create a master index file (index.md, index.html, etc.) @@ -243,9 +274,11 @@ prompt: | - Check for typos and grammar issues 13. **Save documentation patterns:** - - Store the documentation style used in memory for future runs + - Store the documentation style used in memory specifically for this {{ source_path }} project - Remember any project-specific conventions discovered - Save successful example patterns for reuse + - Create or update .goosehints file in {{ source_path }} with documentation preferences + - Consider updating AGENTS.md with documentation standards for future reference 14. **Generate summary report:** - List all files documented From 02c3a9421221919af849fb92025f781209f4b652 Mon Sep 17 00:00:00 2001 From: Arya Pratap Singh Date: Sat, 11 Oct 2025 04:13:54 +0530 Subject: [PATCH 3/4] fixtures Signed-off-by: Arya Pratap Singh --- .../recipes/code-documentation-generator.yaml | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml index 21102eb3f1bc..a76fb25ee3e1 100644 --- a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml +++ b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml @@ -112,7 +112,7 @@ instructions: | 2. **Check for existing documentation:** - Look for existing doc files, READMEs, or inline documentation - Check if there are documentation standards already in use - - Retrieve any stored documentation preferences from memory + - Check for `.goosehints`, `AGENTS.md`, or `DOCS_GUIDELINES.md` files with documentation preferences - If documentation already exists, analyze it to maintain consistency in style and format - Preserve existing documentation structure while filling in gaps for undocumented items - Extract inline docstrings/comments to use as foundation for generated documentation @@ -123,9 +123,8 @@ instructions: | - For JavaScript/TypeScript: Look for JSDoc standards - For Rust: Look for rustdoc conventions - For Go: Look for godoc conventions - - Store the documentation standards in memory specifically for this {{ source_path }} project - - Consider creating a .goosehints file or updating AGENTS.md in the project root to persist these standards - - Check if .goosehints or AGENTS.md already exists and use those guidelines if present + - Check if `.goosehints` or `AGENTS.md` already exists and use those guidelines if present + - If no local guidelines exist, prepare to create them based on detected language standards ## Phase 2: Code Analysis and Extraction @@ -274,11 +273,12 @@ instructions: | - Check for typos and grammar issues 13. **Save documentation patterns:** - - Store the documentation style used in memory specifically for this {{ source_path }} project - - Remember any project-specific conventions discovered - - Save successful example patterns for reuse - - Create or update .goosehints file in {{ source_path }} with documentation preferences - - Consider updating AGENTS.md with documentation standards for future reference + - Create or update `.goosehints` file in {{ source_path }} with documentation preferences + - Store documentation style, format preferences, and project-specific conventions + - Include example patterns that worked well + - Consider updating `AGENTS.md` with documentation standards for team reference + - Optionally create `DOCS_GUIDELINES.md` with detailed documentation style guide + - Reference memory extension only for retrieving these guidelines (do not store full documentation or results in memory) 14. **Generate summary report:** - List all files documented @@ -304,5 +304,7 @@ instructions: | 3. Location of generated documentation files 4. Quick preview of the documentation structure 5. Suggestions for improving inline code documentation + 6. Confirmation that documentation guidelines have been saved to `.goosehints` or `AGENTS.md` - Remember to save documentation preferences to memory for future consistency! + **Note**: Documentation preferences and patterns are stored in repository files (`.goosehints`, `AGENTS.md`, or `DOCS_GUIDELINES.md`) rather than memory to avoid cluttering the LLM context on unrelated tasks. + From 1a78ddc4cfc85e18bdc232bcc6aaa761d693ab12 Mon Sep 17 00:00:00 2001 From: Arya Pratap Singh Date: Thu, 16 Oct 2025 06:30:05 +0530 Subject: [PATCH 4/4] clean and remove unused component Signed-off-by: Arya Pratap Singh --- .../data/recipes/code-documentation-generator.yaml | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml index a76fb25ee3e1..b4d0b6d01ebf 100644 --- a/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml +++ b/documentation/src/pages/recipes/data/recipes/code-documentation-generator.yaml @@ -10,7 +10,7 @@ activities: - Generate documentation with descriptions and usage examples - Create API reference documentation with type information - Build interactive documentation with cross-references - - Remember documentation patterns for consistency + - Store documentation patterns in repository files for consistency prompt: | You are a Code Documentation Generator that creates comprehensive, well-structured documentation for codebases. @@ -21,7 +21,7 @@ prompt: | - Generate consistent documentation following best practices - Create usage examples and code snippets - Build cross-referenced documentation with links - - Remember project-specific documentation styles + - Store project-specific documentation styles in repository files - Research documentation standards for the detected language IMPORTANT: Always detect the programming language first and apply language-specific documentation standards. @@ -71,13 +71,6 @@ extensions: bundled: true description: For file operations, code analysis, and documentation generation - - type: builtin - name: memory - display_name: Memory - timeout: 300 - bundled: true - description: For storing documentation patterns and maintaining consistency - - type: builtin name: browser display_name: Browser @@ -278,7 +271,6 @@ instructions: | - Include example patterns that worked well - Consider updating `AGENTS.md` with documentation standards for team reference - Optionally create `DOCS_GUIDELINES.md` with detailed documentation style guide - - Reference memory extension only for retrieving these guidelines (do not store full documentation or results in memory) 14. **Generate summary report:** - List all files documented