DocBuddy

DocBuddy is a Visual Studio Code extension that creates and maintains file-level Markdown documentation outside your source code.

It keeps documentation local, maps docs to source files, and appends notes and change history without polluting code files with large inline comments.

Repository: Scifiknux/docbuddy

Current Status

This repository currently contains an initial scaffold with core command flows and document services.

Implemented:

• Create/open paired docs for the active file
• Add note entries from selected code ranges
• Append latest Git commit metadata to doc history
• Optional auto-create behavior on file save via config
• AI save summaries from source code into doc ## Summary (optional)
• AI commit "why" explanation during history update (optional)

Planned (not yet implemented in this scaffold):

• Sidebar and richer editor visualization (decorations, CodeLens, hover previews)
• Sticky-anchor relocation across large refactors

Features (Implemented)

Paired Documentation Files

• One Markdown doc per source file
• Stored under .vscode/docbuddy/
• Path mirrors source path
• Auto-adds .vscode/docbuddy/ to .gitignore
• Opens in a separate editor panel to the right of the active code file
• Opens as a normal Markdown text document (fully user-editable)
• Automatically opens when you switch to a source file (configurable)
• Follows file renames by moving the paired doc to the new mapped path
• Keeps only one DocBuddy markdown tab open at a time
• Refreshes metadata - Updated: timestamp when DocBuddy modifies the paired doc

Example:

src/app/index.html
-> .vscode/docbuddy/src/app/index.html.md

Review-Style Notes

• Create a note from current selection
• Captures line range, timestamp, content, snippet hash, and snippet preview
• Appends to the paired Markdown doc

Change History

• Fetches latest commit metadata for the active file
• Appends a history entry to the paired Markdown doc
• Optionally appends AI "why" explanation for the latest commit patch
• Skips appending when that commit hash already exists in doc history

AI Save Summary

• On file save, optionally sends current source code to AI
• Rewrites the ## Summary section with script purpose and key functions
• Shows status while generating, plus error details via toast + DocBuddy AI output channel
• Skips write when generated summary is unchanged from existing ## Summary
• Prompts AI to keep summaries concise (short purpose + limited bullets)
• Allows slightly more detail for function-level responsibilities while remaining concise

Auto Create on Save

• Controlled by docbuddy.autoCreateOnSave
• When enabled, ensures docs exist on save

Commands

• DocBuddy: Create documentation for file
• DocBuddy: Add note from selection
• DocBuddy: Open paired doc
• DocBuddy: Update change history
• DocBuddy: Toggle AI save summary

Editor Action

• A DocBuddy button is available in the active editor title bar (top-right).
• Clicking it runs DocBuddy: Open paired doc.
• The button is hidden while a DocBuddy markdown file is active to prevent nested "doc of doc" panels.

Configuration

Currently available setting:

{
  "docbuddy.autoCreateOnSave": false,
  "docbuddy.autoOpenOnEditorChange": true
}

AI settings (scaffolded in Settings UI):

{
  "docbuddy.ai.enabled": false,
  "docbuddy.ai.endpointUrl": "",
  "docbuddy.ai.model": "gpt-4o-mini",
  "docbuddy.ai.authorizationHeader": "",
  "docbuddy.ai.authType": "none",
  "docbuddy.ai.basicUsername": "",
  "docbuddy.ai.basicPassword": "",
  "docbuddy.ai.bearerToken": "",
  "docbuddy.ai.onSaveSummary": false,
  "docbuddy.ai.onCommitExplainWhy": false
}

Notes:

• AI calls require docbuddy.ai.enabled: true and a valid docbuddy.ai.endpointUrl.
• Endpoint is expected to support OpenAI-compatible chat completions.
• If your endpoint requires a specific auth header format, set docbuddy.ai.authorizationHeader (example: Basic MTIzNDp4).

Project Structure

docbuddy/
|-- src/
|   |-- models/      # Type definitions (e.g., notes)
|   |-- services/    # Doc creation, path mapping, git integration
|   |-- utils/       # Helpers (e.g., snippet hashing)
|   `-- extension.ts # Command registration and activation
|-- package.json
`-- tsconfig.json

Development

Prerequisites

• Node.js 18+ (recommended)
• VS Code

Setup

git clone https://github.com/Scifiknux/docbuddy.git && cd docbuddy && npm install && npm run compile

You should cd into the cloned docbuddy folder, not into the VS Code install directory.

Quick Test (Recommended)

• Open the project in VS Code
• In Run and Debug, select Run Extension
• Press F5 to launch an Extension Development Host

Manual Install (VSIX)

Build and package:

npm install && npm run compile && npx @vscode/vsce package

Install the generated .vsix:

code --install-extension docbuddy-*.vsix

Notes

• Docs are intentionally local-first and Git-clean by default.
• See DesignDocument.md for broader architecture and roadmap details.