# Sphinx AI Assistant
A Sphinx extension that adds AI-powered features to documentation pages, making it easier to use your documentation with AI tools.
## Features
### Markdown Export
- **Copy as Markdown**: Convert any documentation page to Markdown format with a single click
- **View as Markdown**: Open the markdown version of the current page in a new browser tab
- Perfect for pasting into ChatGPT, Claude, or other AI tools
- Preserves code blocks, headings, links, and formatting
- Clean conversion that removes navigation, headers, and other non-content elements
### Integration with AI tools
- **Direct AI Chat Links**: Open ChatGPT or Claude with pre-filled documentation context
- **Smart Content Strategy**: Uses pre-generated markdown files for clean, unlimited-length context
- **Customizable AI Providers**: Built-in support for Claude, ChatGPT, and custom AI services
- **No Backend Required**: Pure static files, works on any hosting
- **MCP (Model Context Protocol) integration**: Connect VS Code and Claude to your MCP
## Installation
### Using pip
```bash
pip install sphinx-ai-assistant
```
### Development Installation
```bash
git clone https://github.com/mlazag/sphinx-ai-assistant.git
cd sphinx-ai-assistant
pip install -e .
```
## Usage
### Basic Setup
1. Add the extension to your `conf.py`:
```python
extensions = [
# ... your other extensions
'sphinx_ai_assistant',
]
```
2. Build your documentation:
```bash
sphinx-build -b html docs/ docs/_build/html
```
That's it! The AI Assistant button will now appear on every page:
- Main button: Copy page as Markdown
- Dropdown:
- Copy or view page as Markdown
- Ask Claude and ChatGPT
- Connect to MCP server in VS Code and Claude Desktop
### Configuration
For details, see [example_conf.py](example_conf.py)
You can customize the extension in your `conf.py`:
```python
# Enable or disable the extension (default: True)
ai_assistant_enabled = True
# Button position: 'sidebar' or 'title' (default: 'sidebar')
# 'sidebar': Places button in the right sidebar (above TOC in Furo)
# 'title': Places button near the page title
ai_assistant_position = 'sidebar'
# CSS selector for content to convert (default: 'article')
# For Furo theme, you might want: 'article'
# For other themes, adjust as needed
ai_assistant_content_selector = 'article'
# Enable/disable specific features (default: as shown)
ai_assistant_features = {
'markdown_export': True, # Copy to clipboard
'view_markdown': True, # View as Markdown in new tab
'ai_chat': True, # AI chat links
'mcp_integration': False, # Not yet implemented
}
# Build-time markdown generation from topics
ai_assistant_generate_markdown = True
# Patterns to exclude from markdown generation
ai_assistant_markdown_exclude_patterns = [
'genindex',
'search',
'py-modindex',
'_sources', # Exclude source files
]
# llms.txt generation
ai_assistant_generate_llms_txt = True
ai_assistant_base_url = 'https://docs.example.com' # Or use html_baseurl
# AI provider configuration
ai_assistant_providers = {
'claude': {
'enabled': True,
'label': 'Ask Claude',
'description': 'Ask Claude about this topic.',
'icon': 'anthropic-logo.svg',
'url_template': 'https://claude.ai/new?q={prompt}',
'prompt_template': 'Get familiar with the documentation content at {url} so that I can ask questions about it.',
},
'chatgpt': {
'enabled': True,
'label': 'Ask ChatGPT',
'description': 'Ask ChatGPT about this topic.',
'icon': 'chatgpt-logo.svg',
'url_template': 'https://chatgpt.com/?q={prompt}',
'prompt_template': 'Get familiar with the documentation content at {url} so that I can ask questions about it.',
},
# Example: Custom AI provider
'custom': {
'enabled': True,
'label': 'Ask Perplexity',
'url_template': 'https://www.perplexity.ai/?q={prompt}',
'prompt_template': 'Analyze this documentation: {url}',
},
}
```
## How It Works
### Markdown Conversion
When you click "Copy content":
1. The extension identifies the main content area of the page
2. Removes non-content elements (navigation, headers, footers, etc.)
3. Converts the HTML to clean Markdown using [Turndown.js](https://github.com/mixmark-io/turndown)
4. Copies the result to your clipboard
5. Shows a confirmation notification
The converted Markdown includes:
- All text content
- Headings (with proper ATX-style formatting)
- Code blocks (with language syntax highlighting preserved)
- Links and images
- Lists and tables
- Block quotes
### AI Chat Integration
When you click "Ask Claude" or "Ask ChatGPT":
**With build-time markdown generation (recommended):**
1. Extension checks if `.md` file exists for current page
2. Opens AI chat with clean URL to markdown file
3. AI can fetch unlimited content directly from your server
**Without markdown generation (fallback):**
1. Converts page to markdown using JavaScript
2. Embeds markdown in URL query parameter
3. Truncates if needed (URL length limits)
## Examples
### Using with AI Tools
After copying a page as Markdown, you can paste it into:
**ChatGPT/Claude:**
```
Here's the documentation for [feature]:
[paste markdown here]
Can you help me understand how to use this?
```
**Cursor/VS Code:**
```
# Context from docs
[paste markdown here]
# Question
How do I implement this in my project?
```
## Development
### Project Structure
```
sphinx-ai-assistant/
├── sphinx_ai_assistant/
│ ├── __init__.py # Main extension module
│ └── static/
│ ├── ai-assistant.js # JavaScript functionality
│ ├── ai-assistant.css # Styling
│ └── *.svg # Icons
├── pyproject.toml # Package configuration
└── README.md # This file
```
### Building Documentation
```bash
cd docs/
sphinx-build -b html . _build/html
```
Creates:
```
docs/_build/html/
├── index.html
├── index.md # Generated markdown
├── tutorial.html
├── tutorial.md # Generated markdown
└── llms.txt # List of all markdown pages
```
## Theme Compatibility
Currently optimized for:
- **Furo** - Full support with sidebar integration
- **Alabaster** - Supported
- **Read the Docs** - Supported
- **Book Theme** - Supported
The extension should work with most themes but may require CSS adjustments.
## Troubleshooting
### Markdown files not generated
```bash
# Install dependencies
pip install beautifulsoup4 markdownify
# Check configuration
grep ai_assistant_generate_markdown conf.py
# Rebuild
sphinx-build -b html docs/ docs/_build/html
```
### AI chat has no content
1. Check if `.md` file exists:
```bash
curl -I https://your-docs.com/page.md
```
2. Check browser console for errors
### Markdown features not working
This happens when `.md` file doesn't exist.
Solution: Generate `.md` files with `ai_assistant_generate_markdown = True`
## Performance
### Build Time
- Adds few seconds per 100 pages for markdown generation
### Runtime
- **With .md files:** Instant (just opens URL)
- **Without .md files:** 100-500ms for first conversion
- Cached for subsequent uses
### File Size
- Markdown files are 40-60% smaller than HTML
- Example: 45 KB HTML → 18 KB Markdown
## License
MIT License - see LICENSE file for details
## Questions or Issues?
- Check the [example_conf.py](example_conf.py)
- Open an [issue](https://github.com/mlazag/sphinx-ai-assistant/issues)
- Start a [discussion](https://github.com/mlazag/sphinx-ai-assistant/discussions)
## Acknowledgments
- Built with [Turndown.js](https://github.com/mixmark-io/turndown) for HTML to Markdown conversion
- Uses [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) and [markdownify](https://github.com/matthewwithanm/python-markdownify) for build-time conversion
- Designed to work seamlessly with the [Furo](https://github.com/pradyunsg/furo) Sphinx theme
- Inspired by the need to make documentation more AI-friendly
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-ai-assistant",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sphinx, documentation, ai, mcp, markdown",
"author": "Mladen Zagorac",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ff/05/f8532278a6b1bc565aa881415993d5903d0c4942af1cfcf15ec44ac04032/sphinx_ai_assistant-0.1.1.tar.gz",
"platform": null,
"description": "# Sphinx AI Assistant\n\nA Sphinx extension that adds AI-powered features to documentation pages, making it easier to use your documentation with AI tools.\n\n## Features\n\n### Markdown Export\n- **Copy as Markdown**: Convert any documentation page to Markdown format with a single click\n- **View as Markdown**: Open the markdown version of the current page in a new browser tab\n- Perfect for pasting into ChatGPT, Claude, or other AI tools\n- Preserves code blocks, headings, links, and formatting\n- Clean conversion that removes navigation, headers, and other non-content elements\n\n### Integration with AI tools\n- **Direct AI Chat Links**: Open ChatGPT or Claude with pre-filled documentation context\n- **Smart Content Strategy**: Uses pre-generated markdown files for clean, unlimited-length context\n- **Customizable AI Providers**: Built-in support for Claude, ChatGPT, and custom AI services\n- **No Backend Required**: Pure static files, works on any hosting\n- **MCP (Model Context Protocol) integration**: Connect VS Code and Claude to your MCP\n\n## Installation\n\n### Using pip\n\n```bash\npip install sphinx-ai-assistant\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/mlazag/sphinx-ai-assistant.git\ncd sphinx-ai-assistant\npip install -e .\n```\n\n## Usage\n\n### Basic Setup\n\n1. Add the extension to your `conf.py`:\n\n```python\nextensions = [\n # ... your other extensions\n 'sphinx_ai_assistant',\n]\n```\n\n2. Build your documentation:\n\n```bash\nsphinx-build -b html docs/ docs/_build/html\n```\n\nThat's it! The AI Assistant button will now appear on every page:\n- Main button: Copy page as Markdown\n- Dropdown:\n - Copy or view page as Markdown\n - Ask Claude and ChatGPT\n - Connect to MCP server in VS Code and Claude Desktop\n\n\n\n### Configuration\n\nFor details, see [example_conf.py](example_conf.py)\n\nYou can customize the extension in your `conf.py`:\n\n```python\n# Enable or disable the extension (default: True)\nai_assistant_enabled = True\n\n# Button position: 'sidebar' or 'title' (default: 'sidebar')\n# 'sidebar': Places button in the right sidebar (above TOC in Furo)\n# 'title': Places button near the page title\nai_assistant_position = 'sidebar'\n\n# CSS selector for content to convert (default: 'article')\n# For Furo theme, you might want: 'article'\n# For other themes, adjust as needed\nai_assistant_content_selector = 'article'\n\n# Enable/disable specific features (default: as shown)\nai_assistant_features = {\n 'markdown_export': True, # Copy to clipboard\n 'view_markdown': True, # View as Markdown in new tab\n 'ai_chat': True, # AI chat links\n 'mcp_integration': False, # Not yet implemented\n}\n\n# Build-time markdown generation from topics\nai_assistant_generate_markdown = True\n\n# Patterns to exclude from markdown generation\nai_assistant_markdown_exclude_patterns = [\n 'genindex',\n 'search',\n 'py-modindex',\n '_sources', # Exclude source files\n]\n\n# llms.txt generation\nai_assistant_generate_llms_txt = True\nai_assistant_base_url = 'https://docs.example.com' # Or use html_baseurl\n\n# AI provider configuration\nai_assistant_providers = {\n 'claude': {\n 'enabled': True,\n 'label': 'Ask Claude',\n 'description': 'Ask Claude about this topic.',\n 'icon': 'anthropic-logo.svg',\n 'url_template': 'https://claude.ai/new?q={prompt}',\n 'prompt_template': 'Get familiar with the documentation content at {url} so that I can ask questions about it.',\n },\n 'chatgpt': {\n 'enabled': True,\n 'label': 'Ask ChatGPT',\n 'description': 'Ask ChatGPT about this topic.',\n 'icon': 'chatgpt-logo.svg',\n 'url_template': 'https://chatgpt.com/?q={prompt}',\n 'prompt_template': 'Get familiar with the documentation content at {url} so that I can ask questions about it.',\n },\n # Example: Custom AI provider\n 'custom': {\n 'enabled': True,\n 'label': 'Ask Perplexity',\n 'url_template': 'https://www.perplexity.ai/?q={prompt}',\n 'prompt_template': 'Analyze this documentation: {url}',\n },\n}\n```\n\n## How It Works\n\n### Markdown Conversion\n\nWhen you click \"Copy content\":\n\n1. The extension identifies the main content area of the page\n2. Removes non-content elements (navigation, headers, footers, etc.)\n3. Converts the HTML to clean Markdown using [Turndown.js](https://github.com/mixmark-io/turndown)\n4. Copies the result to your clipboard\n5. Shows a confirmation notification\n\nThe converted Markdown includes:\n- All text content\n- Headings (with proper ATX-style formatting)\n- Code blocks (with language syntax highlighting preserved)\n- Links and images\n- Lists and tables\n- Block quotes\n\n### AI Chat Integration\n\nWhen you click \"Ask Claude\" or \"Ask ChatGPT\":\n\n**With build-time markdown generation (recommended):**\n1. Extension checks if `.md` file exists for current page\n2. Opens AI chat with clean URL to markdown file\n3. AI can fetch unlimited content directly from your server\n\n**Without markdown generation (fallback):**\n1. Converts page to markdown using JavaScript\n2. Embeds markdown in URL query parameter\n3. Truncates if needed (URL length limits)\n\n## Examples\n\n### Using with AI Tools\n\nAfter copying a page as Markdown, you can paste it into:\n\n**ChatGPT/Claude:**\n```\nHere's the documentation for [feature]:\n\n[paste markdown here]\n\nCan you help me understand how to use this?\n```\n\n**Cursor/VS Code:**\n```\n# Context from docs\n\n[paste markdown here]\n\n# Question\nHow do I implement this in my project?\n```\n\n## Development\n\n### Project Structure\n\n```\nsphinx-ai-assistant/\n\u251c\u2500\u2500 sphinx_ai_assistant/\n\u2502 \u251c\u2500\u2500 __init__.py # Main extension module\n\u2502 \u2514\u2500\u2500 static/\n\u2502 \u251c\u2500\u2500 ai-assistant.js # JavaScript functionality\n\u2502 \u251c\u2500\u2500 ai-assistant.css # Styling\n\u2502 \u2514\u2500\u2500 *.svg # Icons\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n### Building Documentation\n\n```bash\ncd docs/\nsphinx-build -b html . _build/html\n```\n\nCreates:\n```\ndocs/_build/html/\n\u251c\u2500\u2500 index.html\n\u251c\u2500\u2500 index.md # Generated markdown\n\u251c\u2500\u2500 tutorial.html\n\u251c\u2500\u2500 tutorial.md # Generated markdown\n\u2514\u2500\u2500 llms.txt # List of all markdown pages\n```\n\n## Theme Compatibility\n\nCurrently optimized for:\n- **Furo** - Full support with sidebar integration\n- **Alabaster** - Supported\n- **Read the Docs** - Supported\n- **Book Theme** - Supported\n\nThe extension should work with most themes but may require CSS adjustments.\n\n## Troubleshooting\n\n### Markdown files not generated\n\n```bash\n# Install dependencies\npip install beautifulsoup4 markdownify\n\n# Check configuration\ngrep ai_assistant_generate_markdown conf.py\n\n# Rebuild\nsphinx-build -b html docs/ docs/_build/html\n```\n\n### AI chat has no content\n\n1. Check if `.md` file exists:\n ```bash\n curl -I https://your-docs.com/page.md\n ```\n\n2. Check browser console for errors\n\n### Markdown features not working\n\nThis happens when `.md` file doesn't exist.\n\nSolution: Generate `.md` files with `ai_assistant_generate_markdown = True`\n\n## Performance\n\n### Build Time\n- Adds few seconds per 100 pages for markdown generation\n\n### Runtime\n- **With .md files:** Instant (just opens URL)\n- **Without .md files:** 100-500ms for first conversion\n- Cached for subsequent uses\n\n### File Size\n- Markdown files are 40-60% smaller than HTML\n- Example: 45 KB HTML \u2192 18 KB Markdown\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Questions or Issues?\n\n- Check the [example_conf.py](example_conf.py)\n- Open an [issue](https://github.com/mlazag/sphinx-ai-assistant/issues)\n- Start a [discussion](https://github.com/mlazag/sphinx-ai-assistant/discussions)\n\n## Acknowledgments\n\n- Built with [Turndown.js](https://github.com/mixmark-io/turndown) for HTML to Markdown conversion\n- Uses [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) and [markdownify](https://github.com/matthewwithanm/python-markdownify) for build-time conversion\n- Designed to work seamlessly with the [Furo](https://github.com/pradyunsg/furo) Sphinx theme\n- Inspired by the need to make documentation more AI-friendly\n",
"bugtrack_url": null,
"license": null,
"summary": "A Sphinx extension that adds AI assistant features to documentation pages",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/mlazag/sphinx-ai-assistant",
"Issues": "https://github.com/mlazag/sphinx-ai-assistant/issues",
"Repository": "https://github.com/mlazag/sphinx-ai-assistant",
"changelog": "https://github.com/mlazag/sphinx-ai-assistant/blob/master/CHANGELOG.md",
"download": "https://pypi.org/project/sphinx-ai-assistant/",
"source": "https://github.com/mlazag/sphinx-ai-assistant"
},
"split_keywords": [
"sphinx",
" documentation",
" ai",
" mcp",
" markdown"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9581d78bf3749ba35471a3ef15d1e165cd75812b26527d40befb0ce36f8b5fd5",
"md5": "5497d3998a67e2c2271ee4c187026607",
"sha256": "ee9d57deb52675ec11f980d5841fb6b51b4bdc7cdaafe2c289b76ab41d526b6e"
},
"downloads": -1,
"filename": "sphinx_ai_assistant-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5497d3998a67e2c2271ee4c187026607",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23988,
"upload_time": "2025-10-28T13:31:51",
"upload_time_iso_8601": "2025-10-28T13:31:51.834326Z",
"url": "https://files.pythonhosted.org/packages/95/81/d78bf3749ba35471a3ef15d1e165cd75812b26527d40befb0ce36f8b5fd5/sphinx_ai_assistant-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ff05f8532278a6b1bc565aa881415993d5903d0c4942af1cfcf15ec44ac04032",
"md5": "419e03676d7db59f9a8b5d19fae218ed",
"sha256": "c61c87c6e10ee54c3f7b39f35f15e511d5864baf7c68d1f072229dc8d4bb1936"
},
"downloads": -1,
"filename": "sphinx_ai_assistant-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "419e03676d7db59f9a8b5d19fae218ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24738,
"upload_time": "2025-10-28T13:31:53",
"upload_time_iso_8601": "2025-10-28T13:31:53.387020Z",
"url": "https://files.pythonhosted.org/packages/ff/05/f8532278a6b1bc565aa881415993d5903d0c4942af1cfcf15ec44ac04032/sphinx_ai_assistant-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 13:31:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mlazag",
"github_project": "sphinx-ai-assistant",
"github_not_found": true,
"lcname": "sphinx-ai-assistant"
}
JSON
