Python Docstring Intelligence 📝

Keep Python documentation alive — generate, sync, validate, measure, and gate it.

Python Docstring Intelligence is a documentation lifecycle tool for Python in VS Code / Cursor — not just a template inserter.

Generate Google / NumPy / Sphinx docstrings
Auto-sync when signatures change (CodeLens)
Run & validate >>> examples
Track coverage in the status bar
Search functions by what they do
Pro: Doc Health score, Doc Gate CI, smart class docs, quality analysis, doc site, git stale detection

✅ Zero config • 🔒 Works offline (license check only for Pro) • 🤝 Pylance / pytest / Sphinx friendly

What makes it different? Other extensions insert a docstring once. This one helps you keep docs truthful — sync, verify examples, measure health, and fail CI when docs rot.

Developed by NextGenCode

🆓 Free vs 💎 Pro

Capability	Free	Pro ($9.99)
Generate docstrings (Google / NumPy / Sphinx)	✅	✅
Coverage status bar	✅	✅
Preview panel, validation, hover links	✅	✅
Auto-update / CodeLens sync	✅	✅
Example validator + tests from examples	✅	✅
Smart Function Finder	✅	✅
Smart generator (meaningful params, Raises from code)	—	✅
Class / dataclass docstrings	—	✅
Doc Health score (status bar + report)	—	✅
Doc Gate (workspace + CI CLI)	—	✅
Quality analyzer, advanced tests	—	✅
Doc site export, git stale detection	—	✅

🛒 Get Pro on Gumroad → then Python Docstring: Activate Pro License

🚀 Version 0.5.0 — Doc Health + Doc Gate + Smart Classes

Pro highlights

📊 Doc Health — one score (coverage + quality + smell signals) in the status bar
🚪 Doc Gate — fail PRs when docs drop below your bar (editor command + CI CLI)
🧠 Smart Generate + Classes — verb-aware summaries, real param text, Raises from raise, class/dataclass docs

Still in Free (from 0.3)

Auto-Update Docstrings — CodeLens when signatures drift
Runtime Example Validator — runs >>> examples
Smart Function Finder — search by documentation content

→ Changelog

🚀 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 (Pro Smart Generate) — Ctrl+Shift+D with license
def calculate_total(price: float, tax: float = 0.08, discount: float = 0) -> float:
    """
    Calculate total.

    Args:
        price (float): Monetary or numeric amount.
        tax (float): Rate or ratio value, optional (default: 0.08).
        discount (float): Floating-point value for discount, optional (default: 0).

    Returns:
        float: Computed numeric result.

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

Free tier still generates structured Google/NumPy/Sphinx scaffolds instantly. Pro upgrades wording, Raises detection, and class support.

📊 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

💎 Pro Showcase (v0.5)

Doc Health

Command Palette → Python Docstring: Show Doc Health Report (Pro)

Blends coverage, quality scores, placeholder detection, and missing Raises into one 0–100 score. Licensed users see it live in the status bar.

Doc Gate (editor + CI)

Command Palette → Python Docstring: Run Doc Gate on Workspace (Pro)

# After compiling the extension / installing the package
npm run doc-gate
# or
node ./out/cli/docGateCli.js .

Optional config in .docstringgate.json:

{
  "minCoverage": 80,
  "minHealth": 60,
  "failOnPlaceholders": true,
  "failOnMissingPublic": true
}

GitHub Actions workflow included: .github/workflows/doc-gate.yml
Set secret DOCSTRING_PRO_KEY to your license key.

Smart Class Docstrings

Place cursor on a class / @dataclass → Generate Class Docstring (Pro) (or Ctrl+Shift+D).

🆚 Why Choose Python Docstring Intelligence?

vs. Other Extensions

Feature	This extension	autoDocstring	Copilot-only
Insert docstring template	✅ Free	✅	✅ (prose)
Coverage tracking	✅ Free	❌	❌
Auto-sync on signature change	✅ Free	❌	❌
Run docstring examples	✅ Free	❌	❌
Search by doc content	✅ Free	❌	⚠️ chat
Doc Health score	✅ Pro	❌	❌
CI Doc Gate	✅ Pro	❌	❌
Class / smart generate	✅ Pro	⚠️ basic	⚠️ unstructured
Offline structure tools	✅	✅	❌ needs cloud

Positioning: Copilot can write nicer sentences. This extension measures, syncs, verifies, and gates documentation so it doesn’t rot in PRs.

💼 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: The core workflow is free and open source (MIT). Optional Pro ($9.99) unlocks Doc Health, Doc Gate, smart/class generation, quality tools, doc site, and stale detection. Ko-fi support is always welcome.

Q: Does it work offline?
A: Yes for Free features — all processing is local. Pro activation talks to Gumroad once; Doc Gate CLI can use DOCSTRING_PRO_KEY in CI.

Q: Is this AI-powered?
A: No LLM is required. Free/Pro generation is rule- and structure-based (names, types, raise statements). That’s intentional: fast, offline, and predictable.

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

[x] Doc Health score (Pro) — v0.5
[x] Doc Gate CLI / CI (Pro) — v0.5
[x] Smart generator + class docs (Pro) — v0.5
[ ] Optional BYOK LLM descriptions (opt-in)
[ ] Sphinx builder integration
[ ] Team coverage trends
[ ] Custom docstring templates via pyproject.toml

💝 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 - Generate, Sync, Validate & Gate

NextGenCode

Python Docstring Intelligence 📝

🆓 Free vs 💎 Pro

🚀 Version 0.5.0 — Doc Health + Doc Gate + Smart Classes

Pro highlights

Still in Free (from 0.3)

🚀 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

💎 Pro Showcase (v0.5)

Doc Health

Doc Gate (editor + CI)

Smart Class Docstrings

🆚 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