📚 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
🛠️ 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.