Python Docstring Intelligence 📝

Smart docstring generator, validator, and coverage tracker for Python developers

Python Docstring Intelligence is the most advanced documentation tool for Python developers. Auto-generate docstrings in Google/NumPy/Sphinx styles, validate examples in real-time, track coverage, and generate unit tests - all with AI-powered intelligence.

⚡ 10x faster than manual documentation • ✅ Zero configuration needed • 🚀 Works with Pylance, PyTest, Sphinx • 🆓 100% Free & Open Source

🎯 What makes it unique? Unlike other docstring generators, we offer revolutionary features: auto-update when code changes, validate examples by running them, and search functions by documentation content - not just names. No other VS Code extension does this.

Developed by NextGenCode - Next generation development tools

🚀 Version 0.3.0 - REVOLUTIONARY UPDATE!

🎯 Three Game-Changing Features:

⚡🔄 Auto-Update Docstrings - Detects code changes, shows CodeLens, one-click sync!
🧪✅ Runtime Example Validator - Executes docstring examples, verifies they work!
🔍📚 Smart Function Finder - Search by documentation content, not just names!

Why This Matters: No other VS Code extension offers these capabilities. Your documentation stays current automatically, examples are verified, and you can find functions by what they do, not what they're called.

→ See v0.3.0 feature guide | → Changelog

🎉 Version 0.2.0 Features

✨ Three Powerful Additions:

😎 Emoji Documentation - Automatic visual hints (⚡ async, 🔒 private, 📌 static)
🔗 Quick Doc Links - Hover over types/modules for instant documentation
🧪 Test Generation - Auto-create unit tests from docstring examples!

→ See v0.2.0 feature guide

🚀 Quick Start

Get started with Python Docstring Intelligence in 60 seconds:

1️⃣ Install

# Search "Python Docstring Intelligence" in VS Code Extensions
# Or press Ctrl+P and run:
ext install nextgencode.python-docstring-intelligence

2️⃣ Open a Python File

Any .py file with functions - the extension activates automatically.

3️⃣ Generate Your First Docstring

Place cursor inside a function (anywhere)
Press Ctrl+Shift+D (or Cmd+Shift+D on Mac)
✨ Complete docstring appears instantly!

4️⃣ Check Coverage

Look at the status bar (bottom right) - you'll see your docstring coverage percentage.

5️⃣ Explore Advanced Features

Preview Panel: Command Palette → "Open Docstring Preview Panel"
Validate: Command Palette → "Validate All Docstrings"
Generate Tests: Right-click function → "Generate Test from Docstring"
Auto-Update: CodeLens appears when function signature changes

🎯 Pro Tip: Configure your preferred style in Settings → Extensions → Python Docstring → Style (Google/NumPy/Sphinx)

🧪 Try It Yourself (60 Seconds!)

Want to see it in action? Here's a 5-step quick demo:

Install the extension (you're already here!)

Open any Python file or create a new one:

def calculate_discount(price: float, discount: float = 0.1) -> float:
    return price * (1 - discount)

Right-click inside the function → Select "Generate Docstring"
- ✨ Watch as a complete docstring appears instantly with parameters, types, and example!
Check the Status Bar (bottom-right corner)
- 📊 See real-time coverage: 📝 50% (1/2 documented)
Modify the function (add a parameter):
```
def calculate_discount(price: float, discount: float = 0.1, tax: float = 0) -> float:
```
- 🔄 Click the "Update Docstring" CodeLens that appears above the function
- The docstring updates automatically with the new tax parameter!

🎯 Pro Tip: Open the Command Palette (Ctrl+Shift+P) and search for "Python Docstring" to see all available commands!

✨ Features

🚀 Auto-Generate Docstrings

Generate complete, well-formatted docstrings with a single command:

Google Style - Clean, readable format used by Google
NumPy Style - Detailed format popular in scientific Python
Sphinx Style - reStructuredText format for Sphinx documentation

# Before
def calculate_total(price: float, tax: float = 0.08, discount: float = 0) -> float:
    return price * (1 + tax) - discount

# After (Google Style) - Press Ctrl+Shift+D
def calculate_total(price: float, tax: float = 0.08, discount: float = 0) -> float:
    """
    Calculate total.

    Args:
        price (float): Description of price.
        tax (float): Description of tax, optional (default: 0.08).
        discount (float): Description of discount, optional (default: 0).

    Returns:
        float: Description of return value.

    Example:
        >>> result = calculate_total(price=100.0, tax=0.08)
    """
    return price * (1 + tax) - discount

📊 Coverage Tracking

Real-time docstring coverage displayed in your status bar:

Live Updates - Coverage updates as you code
Visual Indicators - Color-coded status (green ✓, yellow ⚠, red ✗)
Detailed Reports - Click for comprehensive coverage breakdown
Configurable Thresholds - Set your own coverage goals

✅ Intelligent Validation

Automatic validation of docstrings with helpful diagnostics:

Missing Docstrings - Identifies undocumented functions
Incomplete Docs - Detects missing parameter documentation
Type Mismatches - Warns about undocumented types
Return Values - Ensures return values are documented

🔍 Live Preview Panel

Dedicated panel showing function documentation in real-time:

Instant Preview - See documentation as you navigate
No Hover Required - Persistent view of current function
Signature Display - Shows complete function signature
Parameter List - Organized view of all parameters
Decorator Support - Displays function decorators

📝 Smart Example Generation

Automatically generates usage examples based on function signature:

def connect_database(host: str, port: int = 5432, ssl: bool = True) -> Connection:
    """
    Connect database.

    Args:
        host (str): Description of host.
        port (int): Description of port, optional (default: 5432).
        ssl (bool): Description of ssl, optional (default: True).

    Returns:
        Connection: Description of return value.

    Example:
        >>> result = connect_database(host="localhost")
    """
    pass

😎 Emoji Documentation (NEW!)

Visual hints automatically added to docstrings:

@property
async def user_count(self) -> int:
    """
    Get user count.

    🔒 Property: Access as attribute, not method
    ⚡ Async: This function is asynchronous

    Returns:
        int: Number of users
    """
    return await self.db.count()

🔗 Quick Documentation Links (NEW!)

Hover over Python types and modules for instant docs:

import json  # ← Hover for JSON docs + RFC 7159!
from typing import List  # ← Hover for typing docs!

def process_data(items: list) -> dict:  # ← Hover 'list' and 'dict'!
    return json.loads(...)

🧪 Generate Tests from Docstrings (NEW!)

Write examples → Get tests automatically:

def add(a: int, b: int) -> int:
    """
    Add two numbers.
    
    Example:
        >>> result = add(2, 3)
        >>> assert result == 5
    """
    return a + b

# Command: "Generate Test from Docstring Examples"
# Creates: test_module.py with proper test function!

📦 Installation

From VS Code Marketplace

Open VS Code
Press Ctrl+P / Cmd+P
Type: ext install nextgencode.python-docstring-intelligence
Press Enter

From VSIX File

Download the .vsix file from releases
Open VS Code
Press Ctrl+Shift+P / Cmd+Shift+P
Type: Extensions: Install from VSIX
Select the downloaded file

🎯 Usage

Generate Docstring for Current Function

Place cursor inside a function
Press Ctrl+Shift+D (Windows/Linux) or Cmd+Shift+D (Mac)
Or: Right-click → Generate Docstring
Or: Command Palette → Python Docstring: Generate Docstring

Generate Docstrings for Entire File

Open a Python file
Command Palette (Ctrl+Shift+P)
Type: Python Docstring: Generate Docstrings for Entire File
Confirm the action

View Coverage Report

Click the coverage badge in status bar
Or: Command Palette → Python Docstring: Show Docstring Coverage Report

Open Preview Panel

Command Palette → Python Docstring: Open Docstring Preview Panel
Navigate through functions to see live documentation

Validate Docstrings

Automatic: Validation runs on save (configurable)
Manual: Command Palette → Python Docstring: Validate All Docstrings

Generate Tests from Docstring Examples 🧪

Write docstring with examples (using >>> or Example: section)
Place cursor in function
Command Palette → Python Docstring: Generate Test from Docstring Examples
Test function is created in new file: test_yourmodule.py

Generate Tests for Entire File 🧪

Command Palette → Python Docstring: Generate Test File from Docstring Examples
Creates comprehensive test file for all functions with examples

⚙️ Configuration

Settings

Open VS Code Settings (Ctrl+,) and search for "Python Docstring":

Setting	Description	Default
`pythonDocstring.style`	Docstring style (google/numpy/sphinx)	`google`
`pythonDocstring.includeTypes`	Include type hints in docstrings	`true`
`pythonDocstring.generateExamples`	Auto-generate usage examples	`true`
`pythonDocstring.validateOnSave`	Validate docstrings when saving	`true`
`pythonDocstring.showCoverageInStatusBar`	Show coverage in status bar	`true`
`pythonDocstring.coverageThreshold`	Coverage threshold for warnings (%)	`80`
`pythonDocstring.quoteStyle`	Quote style for docstrings	`"""`
`pythonDocstring.useEmojiDocumentation` 😎	Add emoji hints to docstrings	`true`
`pythonDocstring.showDocumentationLinks` 🔗	Show hover docs for Python types	`true`
`pythonDocstring.usePytestStyle` 🧪	Generate pytest tests (vs unittest)	`true`
`pythonDocstring.generateAsyncTests` 🧪	Generate async test support	`true`

Example Configuration

{
  "pythonDocstring.style": "google",
  "pythonDocstring.includeTypes": true,
  "pythonDocstring.generateExamples": true,
  "pythonDocstring.validateOnSave": true,
  "pythonDocstring.coverageThreshold": 90,
  "pythonDocstring.quoteStyle": "\"\"\"",
  
  // v0.2.0 Features:
  "pythonDocstring.useEmojiDocumentation": true,
  "pythonDocstring.showDocumentationLinks": true,
  "pythonDocstring.usePytestStyle": true,
  "pythonDocstring.generateAsyncTests": true
}

🎨 Docstring Styles

Google Style

def function(param1: str, param2: int) -> bool:
    """
    Short description.

    Args:
        param1 (str): Description of param1.
        param2 (int): Description of param2.

    Returns:
        bool: Description of return value.

    Example:
        >>> result = function(param1="test", param2=42)
    """
    return True

NumPy Style

def function(param1: str, param2: int) -> bool:
    """
    Short description.

    Parameters
    ----------
    param1 : str
        Description of param1.
    param2 : int
        Description of param2.

    Returns
    -------
    bool
        Description of return value.

    Examples
    --------
    >>> result = function(param1="test", param2=42)
    """
    return True

Sphinx Style

def function(param1: str, param2: int) -> bool:
    """
    Short description.

    :param str param1: Description of param1.
    :param int param2: Description of param2.
    :rtype: bool
    :return: Description of return value.

    Example::

        >>> result = function(param1="test", param2=42)
    """
    return True

⌨️ Keyboard Shortcuts

Action	Windows/Linux	Mac
Generate Docstring	`Ctrl+Shift+D`	`Cmd+Shift+D`

Customize shortcuts in: File → Preferences → Keyboard Shortcuts

🚀 Why Choose Python Docstring Intelligence?

vs. Manual Documentation

⚡ 10x Faster - Generate complete docstrings in seconds
✅ Consistent - Uniform style across your entire project
🎯 Complete - Never miss parameters or return values

vs. Other Extensions

🧠 Intelligent - Smart type inference and example generation
📊 Coverage Tracking - Unique real-time coverage indicator
🔍 Live Preview - Dedicated documentation panel
✅ Validation - Built-in docstring quality checks
🎨 Multiple Styles - Google, NumPy, and Sphinx support
😎 Emoji Hints - Visual documentation helpers (v0.2.0)
🔗 Hover Docs - Instant Python module documentation (v0.2.0)
🧪 Test Generation - Auto-generate tests from examples (v0.2.0)

🛠️ Development

Building from Source

# Clone repository
git clone https://github.com/nextgencode/python-docstring-intelligence.git
cd python-docstring-intelligence

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package extension
npm run package

Project Structure

python-docstring-intelligence/
├── src/
│   ├── extension.ts           # Main extension entry point
│   ├── docstringGenerator.ts  # Docstring generation logic
│   ├── pythonParser.ts        # Python code parsing
│   ├── statusBar.ts           # Coverage status bar
│   ├── docstringPanel.ts      # Preview panel WebView
│   ├── diagnostics.ts         # Validation and diagnostics
│   ├── testGenerator.ts       # Test generation (v0.2.0)
│   └── hoverProvider.ts       # Documentation hover (v0.2.0)
├── package.json               # Extension manifest
├── tsconfig.json              # TypeScript configuration
└── README.md                  # This file

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

🐛 Issues & Support

Found a bug? Have a feature request?

📧 Email: support@nextgencode.dev
🐛 Issues: GitHub Issues
🌐 Website: nextgencode.dev

🆚 Why Choose Python Docstring Intelligence?

vs. Other Extensions

Feature	Python Docstring Intelligence	autoDocstring	Python Docstring Generator	Kite
Auto-Generate Docstrings	✅ Google/NumPy/Sphinx	✅ Multiple styles	✅ Limited styles	✅ Basic
Real-Time Coverage Tracking	✅ Live status bar	❌	❌	❌
Live Preview Panel	✅ Dedicated WebView	❌	❌	❌
Docstring Validation	✅ Full validation	⚠️ Basic	❌	❌
Auto-Update on Changes	✅ CodeLens indicator	❌	❌	❌
Example Validator	✅ Runs examples	❌	❌	❌
Test Generation	✅ From examples	❌	❌	❌
Smart Function Search	✅ By documentation	❌	❌	⚠️ AI-based
Emoji Hints	✅ Visual indicators	❌	❌	❌
Hover Documentation	✅ Python stdlib	❌	❌	✅ AI-powered
Keyboard Shortcut	✅ Ctrl+Shift+D	✅ Customizable	✅	⚠️ Various
Free & Open Source	✅ MIT License	✅ MIT	✅	❌ Freemium
Active Development	✅ Regular updates	⚠️ Occasional	⚠️ Slow	✅

🎯 Unique Features No Other Extension Has:

⚡ Auto-update docstrings when code changes (v0.3.0)
🧪 Validate docstring examples by running them (v0.3.0)
🔍 Search functions by what they do, not what they're called (v0.3.0)
📊 Real-time coverage tracking in status bar
👁️ Live preview panel with navigation

💼 Perfect For

📊 Data Scientists & ML Engineers

NumPy-style docstrings for scientific Python
Coverage tracking for notebooks
Quick documentation without leaving workflow

🏢 Enterprise & Team Leads

Enforce documentation standards
Track team documentation coverage
Consistent style across projects

🚀 API Developers

Sphinx-style for API documentation
Example validation ensures accuracy
Auto-generate tests from docs

🎓 Educators & Students

Learn documentation best practices
See examples of good docstrings
Build professional coding habits

🔧 Open Source Maintainers

Improve project documentation
Onboard contributors faster
Professional documentation with zero effort

❓ Frequently Asked Questions

General

Q: Is this extension free?
A: Yes! 100% free and open source under MIT license. Optional Ko-fi support helps development.

Q: Does it work offline?
A: Yes, completely offline. No cloud services, no API calls, all processing is local.

Q: Which Python versions are supported?
A: Python 3.7+ syntax. Works with any Python file, no runtime required.

Features

Q: How is this different from autoDocstring?
A: We offer unique features like real-time coverage tracking, auto-update on code changes, example validation, test generation, and smart function search. See comparison table above.

Q: Can I customize the docstring style?
A: Yes! Choose between Google, NumPy, or Sphinx styles in Settings. Customize templates and behavior.

Q: Does it work with Pylance/Pyright?
A: Yes! Fully compatible with Pylance, Pylint, mypy, and all major Python tools.

Q: Will it overwrite my existing docstrings?
A: No, it only generates missing docstrings. For updates, it shows a CodeLens indicator that you click manually.

Q: Can I use it in Jupyter notebooks?
A: Yes! Works in .py files and Jupyter notebook cells in VS Code.

Technical

Q: Does it require internet connection?
A: No, everything runs locally in VS Code. No telemetry, no cloud services.

Q: How does the example validator work?
A: It extracts >>> code examples from docstrings and runs them in a Python subprocess, reporting any errors.

Q: Can I disable specific features?
A: Yes! All features can be disabled individually in Settings → Extensions → Python Docstring Intelligence.

Q: Does it support type hints?
A: Yes! It reads and includes type hints from function signatures in generated docstrings.

Q: What about async functions?
A: Fully supported! Adds ⚡ emoji hint and proper async documentation.

Troubleshooting

Q: The coverage shows 0%, but I have docstrings?
A: Make sure docstrings use triple quotes (""") and are directly after the function definition.

Q: Ctrl+Shift+D doesn't work?
A: Check if another extension is using this shortcut. You can customize it in Keyboard Shortcuts settings.

Q: Can't see the status bar coverage?
A: Make sure you have a Python file open and the extension is activated (check status bar for errors).

Q: How do I report bugs?
A: Open an issue on GitHub Issues with your Python code example and VS Code version.

🔍 Search Keywords & Use Cases

Documentation Tools: Python documentation generator • Auto docstring • Docstring automation • Code documentation • API documentation builder • Python doc generator

Productivity: Developer productivity tools • Code quality tools • Python development tools • VS Code Python extensions • Coding automation • Time-saving tools

Standards & Styles: Google style docstring • NumPy docstring format • Sphinx documentation • reStructuredText • PEP 257 • Python documentation standards

Code Quality: Code coverage tracker • Documentation coverage • Code validator • Lint documentation • Clean code • Best practices

Testing & Validation: Test generation • Unit test automation • PyTest integration • Example validator • Doctest • Test from documentation

Python Ecosystem: Pylance compatible • Pylint integration • mypy support • Black formatter • Python type hints • Type annotations

Team & Enterprise: Team documentation • Code review tools • Documentation standards • Enterprise Python • Professional development • Code maintainability

Learning & Education: Python learning tools • Documentation examples • Coding best practices • Professional Python • Code quality education

📊 Roadmap

[ ] AI-powered docstring descriptions
[ ] Multi-language support (TypeScript, JavaScript, Java)
[ ] Integration with Sphinx documentation builder
[ ] Team coverage reports and trends
[ ] Custom docstring templates

💝 Support & Feedback

Enjoying Python Docstring Intelligence?

Your feedback helps make this extension better! If you find it useful:

⭐ Rate on VS Code Marketplace - Share your experience (takes 30 seconds)
🐛 Report Issues - Help us improve
💡 Suggest Features - Share your ideas

Support Development

This extension is free and open source. If it saves you time and you'd like to support continued development:

☕ Buy me a coffee on Ko-fi

Every coffee helps fuel late-night coding sessions!

Made with ❤️ by NextGenCode

Building tools for the next generation of developers

Website • GitHub • Ko-fi

Python Docstring Intelligence - Auto-Generate, Validate & Track

NextGenCode

Python Docstring Intelligence 📝

🚀 Version 0.3.0 - REVOLUTIONARY UPDATE!

🎯 Three Game-Changing Features:

🎉 Version 0.2.0 Features

✨ Three Powerful Additions:

🚀 Quick Start

1️⃣ Install

2️⃣ Open a Python File

3️⃣ Generate Your First Docstring

4️⃣ Check Coverage

5️⃣ Explore Advanced Features

🧪 Try It Yourself (60 Seconds!)

✨ Features

🚀 Auto-Generate Docstrings

📊 Coverage Tracking

✅ Intelligent Validation

🔍 Live Preview Panel

📝 Smart Example Generation

😎 Emoji Documentation (NEW!)

🔗 Quick Documentation Links (NEW!)

🧪 Generate Tests from Docstrings (NEW!)

📦 Installation

From VS Code Marketplace

From VSIX File

🎯 Usage

Generate Docstring for Current Function

Generate Docstrings for Entire File

View Coverage Report

Open Preview Panel

Validate Docstrings

Generate Tests from Docstring Examples 🧪

Generate Tests for Entire File 🧪

⚙️ Configuration

Settings

Example Configuration

🎨 Docstring Styles

Google Style

NumPy Style

Sphinx Style

⌨️ Keyboard Shortcuts

🚀 Why Choose Python Docstring Intelligence?

vs. Manual Documentation

vs. Other Extensions

🛠️ Development

Building from Source

Project Structure

📝 License

🤝 Contributing

🐛 Issues & Support

🆚 Why Choose Python Docstring Intelligence?

vs. Other Extensions

💼 Perfect For

📊 Data Scientists & ML Engineers

🏢 Enterprise & Team Leads

🚀 API Developers

🎓 Educators & Students

🔧 Open Source Maintainers

❓ Frequently Asked Questions

General

Features

Technical

Troubleshooting

🔍 Search Keywords & Use Cases

📊 Roadmap

💝 Support & Feedback

Enjoying Python Docstring Intelligence?

Support Development