RepoAgent Documentation

The InterceptHandler is a custom handler that extends logging.Handler. Its purpose is to intercept log records generated by the standard Python logging module and redirect them into the Loguru system.

How it works:

1. Level Mapping: It maps standard logging levels (like INFO or WARNING) to the corresponding Loguru levels. If a mapping is not found, it falls back to the numeric level of the record.
2. Stack Inspection: It uses inspect.currentframe() to traverse the call stack. It searches for the first frame that does not belong to the logging module. This allows Loguru to correctly identify the original source of the log message (the correct file and line number).
3. Emission: It uses logger.opt() to log the message, preserving exception details and the calculated stack depth.

This class is typically used by calling logging.basicConfig(handlers=[InterceptHandler()]) to ensure all standard logs are captured by Loguru.

The Setting instance returned by SettingsManager.get_setting() is a composite object containing two primary configuration groups:

1. project (ProjectSettings): Manages repository-specific settings.

   • target_repo: Path to the target repository.
   • hierarchy_name: The name used for the documentation hierarchy.
   • log_level: The logging verbosity (e.g., 'INFO').
   • ignore_list: A list of patterns to ignore (e.g., ['*.pyc', '__pycache__']).

2. chat_completion (ChatCompletionSettings): Manages LLM/OpenAI API settings.

   • openai_api_key: Your API key.
   • openai_base_url: The base URL for the API.
   • request_timeout: Timeout in seconds.
   • model: The LLM model name (e.g., 'gpt-3.5-turbo').
   • temperature: Sampling temperature.

Setting(
    project=ProjectSettings(
        target_repo='path/to/repo',
        hierarchy_name='documentation',
        log_level='INFO',
        ignore_list=['*.pyc', '__pycache__']
    ),
    chat_completion=ChatCompletionSettings(
        openai_api_key='your_api_key',
        openai_base_url='https://api.openai.com',
        request_timeout=30,
        model='gpt-3.5-turbo',
        temperature=0.7
    )
)

The DocItem class is the fundamental building block for managing documentation items within a project. It represents individual documentation entities (like files, classes, or functions) and encapsulates their metadata, hierarchical relationships, and code associations.

Key Attributes:

• item_type: The type of the item (defined by DocItemType).
• item_status: The current status of the item (defined by DocItemStatus).
• obj_name: The name of the object.
• code_start_line / code_end_line: The line range of the associated code.
• children: A dictionary mapping child object names to their DocItem instances.
• father: A reference to the parent DocItem.
• tree_path: A list representing the path from the root to this item.
• has_task: A boolean indicating if documentation generation is required for this item or its children.
• who_reference_me / reference_who: Lists of DocItem instances representing incoming and outgoing references.

The TaskManager class is responsible for managing multiple tasks and dispatching them based on their dependencies in a concurrent environment. It uses a thread-safe approach to handle task registration, retrieval, and completion.

Core Workflow

1. Task Registration: Use add_task to register a new task with a list of dependency_task_ids. The manager ensures that the task is only available for processing once all its dependencies are met.
2. Task Retrieval: Workers call get_next_task(process_id) to fetch the next available task. A task is considered available if its dependency list is empty and it is not currently being processed.
3. Task Completion: Once a task is finished, call mark_completed(task_id). This removes the task from the manager and automatically updates the dependency lists of any other tasks that were waiting on it.
4. Completion Check: Use the all_success property to determine if all tasks in the manager have been completed (i.e., the internal task dictionary is empty).

Important Considerations

• Thread Safety: The class uses threading.Lock (task_lock) internally to prevent race conditions during dictionary access.
• Circular Dependencies: Avoid creating circular dependencies when adding tasks, as this will prevent dependent tasks from ever being retrieved.
• Synchronization: If your workflow requires periodic synchronization, you can define a sync_func which the manager will call every ten queries during get_next_task.

# Conceptual usage pattern
manager = TaskManager()

# Add a task with a dependency
dep_id = manager.add_task([], extra_info="root")
task_id = manager.add_task([dep_id], extra_info="child")

# In a worker loop
while not manager.all_success:
    task, tid = manager.get_next_task(process_id=1)
    if tid != -1:
        # ... perform work ...
        manager.mark_completed(tid)

After generating documentation with RepoAgent, navigate to the display directory to set up the visualization environment. This environment requires Node.js 10. You can install Node.js 10 manually or use the provided make commands to automate the process.

Prerequisites

1. Navigate to the display folder:

cd display

2. Ensure you have Node.js 10 installed (using nvm is recommended).

Deployment Steps

You can use the make automation scripts to manage the environment and serve the documentation:

1. Initialize Environment: Run make init_env to install nvm and Node.js 10 (or install Node.js 10 manually).
2. Initialize GitBook: Run make init once to initialize the GitBook environment and install necessary plugins.
3. Generate and Serve: Run make serve to generate the repository book and start the local server.

If you modify configurations or the book.json file, simply run make serve again to redeploy.