Setup & Getting Started

Welcome to DeepDoc! This guide covers everything a developer needs to install, configure, and launch DeepDoc in a new or existing codebase. You'll learn how the configuration system works, how to bootstrap your environment, and how to avoid common pitfalls. For a high-level system overview, see DeepDoc Architecture & System Overview.

Overview

DeepDoc is an AI-powered documentation generator that scans your codebase, plans documentation buckets, and builds a Fumadocs-powered site. The setup process is designed to be fast for new contributors and robust for production teams.

• Installation: DeepDoc is distributed via PyPI and supports optional chatbot features.
• Configuration: Uses a .deepdoc.yaml file at your repo root, with sensible defaults and deep merging.
• Environment: Relies on environment variables for API keys and some runtime toggles.
• CLI: The deepdoc command-line tool orchestrates all workflows.

For details on the documentation pipeline, see Pipeline & Generation Engine. For parsing logic, see Parsing & Source Analysis.

How It Works

The setup and initialization flow for DeepDoc is as follows:

• Steps involving config file creation and environment variables are handled by code in deepdoc/config.py and deepdoc/chatbot/settings.py.
• The CLI commands are documented in CLI Commands & Tooling.
• The documentation pipeline is detailed in Pipeline & Generation Engine.

Key Components

1. Configuration Management

load_config() (deepdoc/config.py:203)

Loads the .deepdoc.yaml config, merging user settings with DEFAULT_CONFIG. If no config file is found, returns defaults.

Parameters:

• path: Path | None — Optional path to config file.

Returns:
dict[str, Any] — The merged configuration.

Example:

from deepdoc.config import load_config
cfg = load_config()  # Loads from .deepdoc.yaml or uses defaults

find_config() (deepdoc/config.py:193)

Walks up the directory tree to locate .deepdoc.yaml.

Returns:
Path | None — Path to config file if found.

save_config() (deepdoc/config.py:215)

Writes a config dictionary to a file.

_deep_merge() (deepdoc/config.py:220 and deepdoc/chatbot/settings.py:67)

Recursively merges two dictionaries, with values from the override dict taking precedence.

Used by:

• load_config() (deepdoc/config.py:203)
• get_chatbot_cfg() (deepdoc/chatbot/settings.py:77)

get_chatbot_cfg() (deepdoc/chatbot/settings.py:77)

Merges chatbot-specific config from the main config using _deep_merge().

Parameters:

• cfg: dict[str, Any] — Main config.

Returns:
dict[str, Any] — Chatbot config.

2. Environment Variable Resolution

resolve_api_key() (deepdoc/config.py:230)

Fetches the LLM API key from the environment variable specified in config.

Example:

from deepdoc.config import resolve_api_key, load_config
cfg = load_config()
api_key = resolve_api_key(cfg)

resolve_service_api_key() (deepdoc/chatbot/settings.py:140)

Fetches a service-specific API key from the environment variable specified in the service config.

3. Chatbot Configuration Helpers

All helpers below live in deepdoc/chatbot/settings.py and are critical if you enable chatbot features.

• chatbot_enabled(cfg) — Checks if chatbot is enabled.
• chatbot_index_dir(repo_root, cfg) — Returns the chatbot index directory.
• chatbot_backend_base_url(cfg, repo_root=None) — Resolves the backend URL, defaulting to local if not configured.
• chatbot_should_start_local_backend(cfg) — Determines if the local backend should be started.
• chatbot_backend_port(cfg, repo_root=None) — Resolves the backend port, using a deterministic hash if not configured.
• chatbot_allowed_origins(cfg) — Returns allowed CORS origins, including dynamic preview ports.

See DeepDoc Chat API Integration and DeepDoc Embedding API Integration for more.

Configuration

Config File: .deepdoc.yaml

Created by deepdoc init (see CLI Commands & Tooling), this YAML file controls all aspects of DeepDoc.

Key sections:

• project_name, description, output_dir, site_dir
• llm: provider, model, API key env var, temperature, etc.
• chatbot: enable/disable, backend config, answer/embedding providers, vector store, retrieval, chunking

Example minimal config:

project_name: My Project
llm:
  provider: anthropic
  model: claude-3-5-sonnet-20241022
  api_key_env: ANTHROPIC_API_KEY
chatbot:
  enabled: true
  answer:
    api_key_env: DEEPDOC_CHAT_API_KEY
  embeddings:
    api_key_env: DEEPDOC_EMBED_API_KEY

Environment Variables

Common Patterns

Initializing a Project

pip install deepdoc

pip install "deepdoc[chatbot]"

deepdoc init

export ANTHROPIC_API_KEY=sk-ant-...
export DEEPDOC_CHAT_API_KEY=sk-chat-...      # If chatbot enabled
export DEEPDOC_EMBED_API_KEY=sk-embed-...    # If chatbot enabled

deepdoc generate

deepdoc serve
# Open http://localhost:3000

Loading Config in Code

from deepdoc.config import load_config
cfg = load_config()
if cfg["chatbot"]["enabled"]:
    # Chatbot-specific logic
    ...

Customizing Chatbot Backend

To point the chatbot backend to a remote service, set chatbot.backend.base_url in .deepdoc.yaml.
To run the backend locally, leave it blank or use a loopback address.

Gotchas & Edge Cases

• Config merging: Both deepdoc/config.py and deepdoc/chatbot/settings.py use deep merging. If you override only part of a nested config (e.g., just chatbot.answer.model), all other defaults are preserved.
• API key resolution: If the environment variable specified in api_key_env is missing, API calls will fail with authentication errors.
• Chatbot preview ports: If you set DEEPDOC_CHATBOT_PREVIEW_PORT, it will add CORS origins for both localhost and 127.0.0.1 at that port.
• Backend port hashing: The default chatbot backend port is deterministically derived from your repo path using CRC32 (_default_chatbot_port() in deepdoc/chatbot/settings.py:156). This avoids port collisions in multi-repo setups.
• YAML pitfalls: Invalid YAML in .deepdoc.yaml will cause startup errors. Use deepdoc config commands to edit safely.

See Also