📚 Doctor Doc

Doctor Doc is a tool to keep documentation code blocks always up to date.

📝 Prerequisites

Before using Doctor Doc, ensure you have the following installed:

Python

Description: Python is a programming language that Doctor Doc uses to execute scripts and manage code blocks.
Installation: You can download and install Python from the official website.

Ollama

Description: Ollama is a local AI model that Doctor Doc uses to analyze and suggest solutions for outdated documentation.
Installation: Follow the instructions on the Ollama website to choose and install a local AI model.

Make sure both Python and Ollama are correctly set up and accessible from your system's PATH.

✨ Features

Provides detailed error messages for outdated code blocks.
Analyzes and suggests solutions for outdated documentation using a user-selectable local AI model.
Removes stale references from the documentation.
Works with commands on all .md files or directly on saving .md files.

🚀 How to Use

Install the Extension: Install the Doctor Doc extension in Visual Studio Code.

Configure Settings: Add the following configuration to your .vscode/settings.json file:

{
  "doctorDoc": {
    "docsFolderPath": "docs",
    "pythonPath": "/usr/bin/python3",
    "codeExtensions": [".ts", ".js", ".vue"],
    "ignoreLanguages": ["mermaid", "bash", "shell", "plaintext", "none"],
    "searchCodeDir": "src"
  }
}

Save a Markdown File: Open and save any Markdown file in your project to sync code blocks in documentation.
Ask AI: Ask the AI why the code block is outdated (available only if previously bound with the save action).
Use Commands: Use the following commands to interact with the extension:
- Check All Docs: Checks all Markdown files in the specified documentation folder for outdated code blocks.

🤖 AI Model Selection

Doctor Doc allows you to select a custom AI model or use the default one for analyzing and suggesting solutions for outdated documentation.

⚙️ Installation

Regardless of whether you use the default or a custom AI model, you must install at least one model from the Ollama website. Follow the instructions provided on the website to download and install the AI model of your choice. Make sure the AI model is correctly set up and accessible from your system's PATH.

🌟 Default AI Model

Description: The default AI model (llama3:8b) is pre-configured to work out-of-the-box with Doctor Doc.
Action: You need to install the default AI model with the following command: ollama run llama3.
Usage: No additional configuration is required if you choose to use the default AI model, you just need to install the default model on your local machine.

🔧 Custom AI Model

Description: You can select a custom AI model to better suit your specific needs.
Action: You need to install your favorite AI model from the Ollama website.
Usage: After clicking the CTA Explain with AI, you can choose your local AI model.

🌐 OpenAI Integration

Description: In addition to local models, you can use OpenAI models for documentation analysis.
Prerequisites: You need a valid OpenAI API key.

Configuration: Add the following configuration to your .vscode/settings.json file:

{
  "doctorDoc": {
    "openaiApiKey": "your-api-key-here",
    "openaiModel": "gpt-4o-mini" // optional, default: gpt-4o-mini
  }
}

Usage: After configuring the API key, you can select the desired OpenAI model when you click on Explain with AI.

🛠️ Commands details

`Check All Docs`

This command checks all Markdown files in the specified documentation folder for outdated code blocks. It scans each file, calculates the hash of each code block, and compares it with the stored hash values. If any code block is outdated, it provides detailed error messages and opens a webview with the details.

🔄 Automatic Updates on Save

The extension automatically updates the documentation when a Markdown file is saved. If any code block is outdated, it provides detailed error messages and opens a webview with the details.

⚙️ Detailed Configuration

`docsFolderPath`

Type: string
Example: "docs"
Description: The path to the documentation folder relative to the project root, which is recursive.

`pythonPath`

Type: string
Example: "/usr/bin/python3"
Description: Path to the Python interpreter.

`codeExtensions`

Type: array
Items: string
Example: [".ts", ".js", ".vue"]
Description: List of code file extensions to be considered.

`ignoreLanguages`

Type: array
Items: string
Example: ["mermaid", "bash", "shell", "plaintext", "none"]
Description: List of languages to ignore in code blocks.

`searchCodeDir`

Type: string
Default: "src"
Description: Path to the source directory relative to the root of the project.

`openaiApiKey`

Type: string
Example: "sk-..."
Description: Your OpenAI API key for using OpenAI models instead of local ones.

`openaiModel`

Type: string
Example: "gpt-4o-mini"
Description: The OpenAI model to use for documentation analysis.

Example

Here is an example of a complete .vscode/settings.json configuration:

{
  "doctorDoc": {
    "docsFolderPath": "docs",
    "pythonPath": "/usr/bin/python3",
    "codeExtensions": [".ts", ".js", ".vue"],
    "ignoreLanguages": ["mermaid", "bash", "shell", "plaintext", "none"],
    "searchCodeDir": "src",
    "openaiApiKey": "your-api-key-here",
    "openaiModel": "gpt-4o-mini"
  }
}

Troubleshooting

If you encounter any issues, please check the following:

Ensure that the pythonPath is correctly set to the path of your Python interpreter.
Ensure that the docsFolderPath is correctly set to the path of your documentation folder.
Ensure that the codeExtensions list includes all the file extensions you want to be considered.
Ensure that the ignoreLanguages list includes all the languages you want to be ignored.
Ensure that the searchCodeDir is correctly set to the path of your source directory.
Make sure you have installed a local AI model using Ollama.
If you fail to install the extension on the Cursor IDE, try running the command: code --install-extension your_vsix_path_file

If the problem persists, please open an issue on the GitHub repository.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Doctor Doc

DoctorDoc