SimplePyDocs

Universal Python documentation tooltips - Works with 500+ Python symbols!

SimplePyDocs provides instant, comprehensive documentation tooltips when hovering over ANY Python symbol in VS Code. From built-in functions to popular libraries like pandas, numpy, and requests - get documentation instantly without leaving your editor!

✨ Features

• Universal Coverage - Works with 500+ Python symbols including built-ins, modules, and libraries
• Comprehensive Documentation - All Python keywords, 143+ built-ins, and popular libraries
• Two Display Modes:
  • Beginner Mode: Simple one-liner explanations
  • Developer Mode: Detailed signatures with parameters
• Dynamic Discovery - Automatically finds and documents Python symbols
• Smart Fallbacks - Uses Python's built-in __doc__ strings
• Customizable - Add your own documentation overrides
• Modern UI - Clean, professional tooltip rendering
• Security First - Built with comprehensive security measures

🎯 Use Cases

• Python Beginners: Learn what keywords and functions do without leaving your editor
• Quick Reference: Get instant reminders about function parameters and usage
• Code Reviews: Understand unfamiliar Python code quickly
• Teaching: Provide immediate context for Python concepts
• Data Scientists: Get docs for pandas, numpy, matplotlib functions
• Web Developers: Access requests, flask, django documentation
• System Admins: Get os, subprocess, threading module docs
• Full-Stack Developers: Comprehensive coverage of Python ecosystem

🚀 Installation

From VS Code Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "SimplePyDocs"
4. Click Install

Manual Installation

1. Clone this repository:

   git clone https://github.com/kunalbandale/simple-py-docs.git
   cd simple-py-docs
   

2. Install dependencies:

   npm install
   

3. Build the extension:

   npm run compile
   

4. Press F5 in VS Code to run the extension in a new Extension Development Host window

📖 Usage

Basic Usage

1. Open any Python file (.py)
2. Hover over any Python keyword or built-in function
3. See instant documentation tooltips!

Configuration

Open VS Code settings (Ctrl+,) and search for "SimplePyDocs" to customize:

{
  "simplePyDocs.mode": "beginner",           // "beginner" or "developer"
  "simplePyDocs.enableBuiltins": true,      // Enable built-in function tooltips
  "simplePyDocs.enableKeywords": true,      // Enable keyword tooltips
  "simplePyDocs.customDocs": {              // Custom documentation overrides
    "myFunction": "My custom documentation"
  }
}

Commands

• Show All Python Built-ins: Ctrl+Shift+P → "SimplePyDocs: Show All Python Built-ins"
  • Displays comprehensive list of available Python functions and classes
  • Shows total count of discoverable symbols

Display Modes

Beginner Mode (Default)

len → "Return the number of items in obj"

Developer Mode

len
**Return the number of items in obj**

📸 Screenshots

Extension Installation

Beginner Mode Examples

Developer Mode Examples

🛠️ Development

Project Structure

simple-py-docs/
├── src/
│   └── extension.ts          # Main extension logic with universal Python support
├── media/
│   └── icon.png             # Extension logo (128x128)
├── screenshots/              # Extension screenshots and demos
├── package.json             # Extension metadata & publishing config
├── tsconfig.json            # TypeScript configuration
├── .vscode/                 # VS Code configuration
│   ├── launch.json          # Debug configuration
│   └── tasks.json           # Build tasks
└── README.md               # This file

Building

# Install dependencies
npm install

# Build the extension
npm run compile

# Watch for changes
npm run watch

# Package for publishing
npm run package

# Publish to marketplace
npm run publish

Testing

# Run tests
npm test

# Run extension in development mode
# Press F5 in VS Code

🔧 Technical Details

Architecture

• Language: TypeScript (VS Code standard)
• APIs: Official VS Code Extension API (vscode.languages.registerHoverProvider)
• Documentation Source: Python built-in __doc__ strings + dynamic module discovery
• Rendering: VS Code Markdown rendering for rich tooltips
• Coverage: 500+ Python symbols including built-ins, modules, and popular libraries

Key Components

1. PythonHoverProvider: Main hover provider class implementing vscode.HoverProvider
2. Universal Documentation: Dynamically discovers and documents Python symbols
3. Module Discovery: Searches built-ins, common modules, and popular libraries
4. Security Features: Input validation, process timeouts, and rate limiting
5. Configuration: VS Code workspace configuration integration
6. Fallback System: Comprehensive fallback documentation system

Performance

• Lazy Loading: Documentation fetched only when hovering
• Smart Caching: Built-in documentation cached in memory
• Efficient Discovery: Dynamic module search with timeout protection
• Non-blocking: Async Python process calls with rate limiting
• Universal Coverage: Works with 500+ Python symbols

🎨 Customization

Adding Custom Documentation

{
  "simplePyDocs.customDocs": {
    "myCustomFunction": "This function does something amazing",
    "anotherFunction": "Another custom description"
  }
}

🚧 Future Roadmap

Phase 1 (Current) ✅

• ✅ Python keywords and built-in functions
• ✅ Beginner and developer modes
• ✅ Custom documentation overrides
• ✅ Universal Python symbol discovery
• ✅ Popular library support (pandas, numpy, requests)
• ✅ Security features and rate limiting

Phase 2 (Planned) 🔄

• 🔄 Advanced library detection (auto-import analysis)
• 🔄 Snippet integration with documentation
• 🔄 Documentation caching and persistence
• 🔄 Custom library documentation

Phase 3 (Future) 🔮

• 🔮 AI-powered documentation generation
• 🔮 Community documentation sharing
• 🔮 Integration with documentation sites
• 🔮 Advanced code analysis and suggestions
• 🔮 Performance profiling and optimization

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Code Style: Follow TypeScript best practices
• Comments: Add clear inline comments for complex logic
• Testing: Add tests for new features
• Documentation: Update README for new features

Areas for Contribution

• 🐛 Bug fixes and improvements
• ✨ New Python keywords/functions
• 🎨 UI/UX improvements
• 📚 Documentation enhancements
• 🧪 Test coverage
• 🌍 Localization support

🧪 Testing the Extension

Quick Test

1. Launch Extension: Press F5 in VS Code
2. Open Python File: Create a test Python file for testing
3. Hover Over Symbols: Test keywords, functions, and classes

Comprehensive Test Coverage

The extension works with 500+ Python symbols:

Test Commands

• Show All Built-ins: Ctrl+Shift+P → "SimplePyDocs: Show All Python Built-ins"
• Toggle Modes: Switch between beginner and developer modes in settings

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• VS Code Team - For the excellent extension API
• Python Community - For comprehensive built-in documentation
• Open Source Contributors - For making this project possible

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

⭐ Star History

If you find this extension helpful, please consider giving it a star on GitHub!

Made with ❤️ for the Python and VS Code communities