DOCSEARCHbyAlgolia
Submit Docs

DocSmith AI Documentation Generator

repository·main·Indexed 41 days ago

https://github.com/aigne-io/aigne-doc-smith

An AI-powered documentation generation system built on the Aigne Framework. DocSmith automates the creation of technical documentation, user guides, and API references by analyzing codebases through an interactive, intent-driven workflow. It features project analysis, user intent inference, and a structure confirmation mechanism to produce structured Markdown documentation. It can be used via the Aigne CLI or as a skill for Claude Code.

Tokens
20.9K
Snippets
39
Records
91
Agent score
50%

What's inside DocSmith

  1. Overview of DocSmith capabilities

    main

    DocSmith is a tool designed to generate and update comprehensive, structured documentation from workspace data sources, including code repositories, text files, and media resources. It produces:

    1. User Intent Descriptions (user-intent.md)
    2. Document Structure Plans (document-structure.yaml)
    3. Hierarchical Markdown Documentation organized in a dedicated workspace.

    It supports technical documentation, user guides, API references, and general documentation maintenance. It uses a persistent task planning mechanism to ensure long-running tasks are traceable and recoverable.

  2. How the DocSmith Document Generation Agent works

    main

    The Document Generation Agent is responsible for creating detailed documentation for a single document path. It follows a structured workflow to ensure technical accuracy and alignment with user intent.

    Core Workflow

    1. Configuration Loading: Automatically reads planning/document-structure.yaml (for hierarchy and source paths), intent/user-intent.md (for target audience and focus), and config.yaml (for locale).
    2. Source Analysis: Reads and analyzes files defined in sourcePaths to extract APIs, classes, functions, and core concepts.
    3. Intent Alignment: Adjusts tone and depth based on the user profile and use cases defined in user-intent.md.
    4. Media Preparation: Locates existing assets and prepares for new technical diagram generation.
    5. Content Generation: Produces Markdown following specific rules for structure, code examples, and navigation.
    6. Persistence & Validation: Saves the document using saveDocument and validates it via checkContent.

    Input Parameters

    • path (Required): A string representing the document path (e.g., /api/overview), which must match an entry in document-structure.yaml.
    • customRequirements (Optional): A string for additional user instructions (e.g., "Focus on security considerations").

  3. Understand the DocSmith workspace directory structure

    main

    DocSmith stores all its state, configurations, and generated outputs in a .aigne/doc-smith/ directory within your project (or your independent workspace).

    Key directories include:

    • config.yaml: The main configuration file.
    • intent/: Stores inferred user intent data.
    • planning/: Stores the planned document structure.
    • docs/: The final generated Markdown documentation (e.g., overview.md, api/).
    • cache/: Temporary data used during processing.

  4. How to load skill resources on demand

    main

    To optimize performance and context usage, skills should not preload all available resources. Instead, follow this loading pattern:

    1. Start with the main skill file: Locate the primary file (e.g., SKILL.md) which contains the workflow overview and references to detailed guides.
    2. Load reference documents on demand: Only read specific guides from the references/ directory when you reach the specific step in a workflow that requires that information.
    3. Avoid preloading: Do not read all reference files at the start of a task.

  5. Understand the DocSmith workspace structure

    main

    DocSmith manages its state and output within a .aigne/doc-smith/ directory in your project root. The structure is as follows:

    • .aigne/doc-smith/config.yaml: The main configuration file.
    • .aigne/doc-smith/intent/: Stores inferred user intent data.
    • .aigne/doc-smith/planning/: Stores the planned documentation structure.
    • .aigne/doc-smith/docs/: The directory containing the actual generated Markdown documentation (e.g., overview.md, api/).
    • .aigne/doc-smith/cache/: Temporary data used during processing.

  6. Decide when to split documentation into sub-documents

    main

    Use the following criteria to determine if a topic should be split into sub-documents or kept as a single document.

    When to Split (Must meet 3-4 conditions)

    • High Content Volume: The parent topic contains 4+ major chapters or is expected to exceed 500 lines.
    • High Independence: Sub-topics have rich, independent content (3+ paragraphs or 3+ sections) and can be understood without heavy reliance on other sub-topics.
    • No Redundancy: There is no significant content overlap between sub-documents or between sub-documents and the parent.
    • Independent Reference: Users frequently need to look up a specific sub-topic individually rather than reading the entire sequence.
    • Example: Splitting an API Reference into User, Order, and Payment sub-documents.

    When NOT to Split (Avoid if any condition applies)

    • Thin Content: Sub-topics are expected to have fewer than 3 paragraphs or lack sufficient source files.
    • High Dependency/Redundancy: Sub-topics overlap significantly or must be read together to be understood.
    • Sequential Steps: The content represents a linear workflow (e.g., Install $\rightarrow$ Configure $\rightarrow$ Run). These should be merged into a single document to reduce navigation overhead.
    • Empty Parent: Splitting would leave the parent document as an empty shell containing only navigation links.
    • Example: A "Quick Start" guide should be one document containing installation, configuration, and first run steps, rather than three separate files.

  7. Understand and use Changeset files

    main

    A Changeset is a structured carrier for batch feedback, written in natural language. It allows users to request multiple modifications at once. Changeset files should be kept in the repository to maintain a history of modification requirements.

    Key Characteristics:

    • Direct Execution: Modification requests in a Changeset are executed directly without requiring secondary user confirmation.
    • Format: Free-form natural language.
    • Content: Typically includes a Summary, Global Semantic Changes, Structural Rewrite Requests, Additional Data/References, Clarifications/Corrections, and Acceptance Criteria.
    • Note on PATCH: It is recommended to mark PATCH operations directly within the document body rather than requiring them to be explicitly written in the Changeset.

  8. Determine content strategy based on document hierarchy

    main

    DocSmith distinguishes between Overview Documents and Detailed Documents based on the presence of children in document-structure.yaml. This determines the level of detail provided.

    Document TypeConditionContent Strategy
    Overview DocumentHas children in document-structure.yamlBrief: 2-4 paragraphs per sub-topic + guiding links. Max 200 words per sub-topic. Max 10 lines per code example.
    Detailed DocumentNo children in document-structure.yamlComprehensive: Full expansion of all details, edge cases, and best practices. Max 25 lines per code example.

    Note: Overview documents should not expand on content that is covered in detail by their child documents.

  9. Use Lucide icons for top-level documentation

    main

    Top-level documents in the documents array can be assigned an icon to improve visual navigation. Icons must follow the lucide:icon-name format.

    Constraints:

    • Only top-level documents require/should use the icon field.
    • Nested documents (those inside a children array) must omit the icon field.
    • Valid icon names can be found at https://lucide.dev/icons.

    Examples:

    • lucide:home
    • lucide:file-text
    • lucide:settings
    • lucide:rocket
    • lucide:code

  10. Identify input types for documentation updates

    main

    DocSmith recognizes three primary ways to trigger documentation updates:

    Input TypeIdentification FeatureNext Step
    Changeset FileUser provides a .md file pathRead the file (see changeset-guide.md)
    PATCH MarkerUser mentions "PATCH marker" or "apply PATCH"Scan documents (see patch-guide.md)
    Natural LanguageDirect description of modification needsAnalyze and classify into modification types

    Natural Language Modification Categories

    • Global Semantic Modification: Rules spanning multiple documents. Keywords: all, unified, entire, delete. Example: "Change all API to API interface".
    • Local Structural Rewrite: Supplementing or reorganizing specific chapters. Keywords: supplement, add, rewrite, reorganize. Example: "Add project background to overview.md".
    • PATCH-level Modification: Precise replacement content. Characterized by providing original text and revised text. (Users are encouraged to use the PATCH marker format for better results).

  11. Handle AFS Image Slots and generate images

    main

    When DocSmith detects that technical images are required but not provided in the data source, it generates an AFS Image Slot placeholder in the documentation. These placeholders use a key field to identify the intended image.

    Process:

    1. Detection: Check if the generated documentation contains AFS Image Slot placeholders.
    2. Storage: Generated images are stored in the assets/ directory, organized by the placeholder's key.
    3. Generation: If slots are found, call the generateImages tool to automatically generate the images for the documentation.

    Images are saved in a structure like: modules/workspace/assets/[key]/images/[language].png.

  12. Core Principles for using DocSmith

    main

    When using DocSmith for documentation tasks, follow these operational principles to ensure consistency and traceability:

    • Workspace First: Always detect and initialize the workspace before performing any operations.
    • Task Planning First: A task_plan.md must be created before starting work. This file must be read before every stage and updated after every stage.
    • Persistent Logging: Record all key decisions, errors, and solutions in task_plan.md to ensure task traceability.
    • Reference-Driven Execution: If reference files are provided for a step, they must be read before execution.
    • Content Standards: All document generation or updates must adhere to the requirements in references/document-content-guide.md.
    • Intent-Based Generation: All planning and generation must be guided by the user intent defined in intent/user-intent.md.
    • Minimum Viable Documentation: Only generate the documents explicitly requested in the user intent.
    • Batch Execution: Prioritize batch execution when generating document content to reduce total execution time.
    • Git Integration: DocSmith automatically commits all changes to Git once generation, updates, or translations are complete.