Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 4 additions & 72 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,11 @@
# Python Examples Documentation Site

This is the source for the GitHub Pages documentation site for python-examples.

## 🚀 Built With

- **Astro** - Fast, content-focused static site generator
- **Academic Paper Design** - Clean, professional typography inspired by research papers
- **Interactive Filtering** - Search and filter examples by category
- **Personality** - Easter eggs and touches that show character

## 🛠️ Development
# Documentation Site Development

Dev commands:
```bash
cd docs

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run dev # localhost:4321
npm run build

# Preview production build
npm run preview
```

## 📁 Structure

```
docs/
├── src/
│ ├── layouts/ # Page layouts
│ ├── pages/ # Astro pages
│ ├── styles/ # Global CSS
│ └── components/ # Reusable components (future)
├── public/ # Static assets
└── astro.config.mjs # Astro configuration
```

## 🎨 Design Philosophy

- **Academic aesthetic** - Serif fonts, paper-like background, numbered sections
- **Monospace code** - JetBrains Mono for all code examples
- **Accent color** - Burnt orange (#d35400) for personality
- **Clean typography** - Crimson Pro for body, Inter for UI elements
- **Interactive** - Search, filters, and easter eggs for engagement

## 🚀 Deployment

The site automatically deploys to GitHub Pages when changes are pushed to master via GitHub Actions.

## 🎯 Features

- ✅ Responsive design
- ✅ Search functionality
- ✅ Category filtering
- ✅ Print-friendly (for actual paper)
- ✅ Easter egg (Konami code)
- ✅ Fast static site generation
- ✅ Academic paper styling

## 📝 Adding New Examples

Edit `src/pages/index.astro` and add to the `examples` array:

```javascript
{
title: 'your-example.py',
description: 'What it does',
category: 'Category Name',
tags: ['tag1', 'tag2'],
difficulty: 'beginner' // or 'intermediate', 'advanced'
}
```

The site will automatically update filters and search.
To add examples, edit `src/pages/index.astro`.
63 changes: 22 additions & 41 deletions docs/src/pages/index.astro
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,6 @@
import Layout from '../layouts/Layout.astro';

const examples = [
// LLM & AI
{
title: 'openai_gpt-example.py',
description: 'Chat completions, streaming, function calling, JSON mode with GPT-4',
category: 'LLM & AI',
tags: ['openai', 'gpt', 'chat', 'streaming'],
difficulty: 'intermediate'
},
{
title: 'anthropic_claude-example.py',
description: 'Claude 3.5 integration with vision, streaming, and extended thinking',
category: 'LLM & AI',
tags: ['anthropic', 'claude', 'vision', 'ai'],
difficulty: 'intermediate'
},
{
title: 'langchain-example.py',
description: 'LangChain framework: chains, memory, RAG, and prompt templates',
category: 'LLM & AI',
tags: ['langchain', 'rag', 'agents', 'chains'],
difficulty: 'advanced'
},
{
title: 'instructor-example.py',
description: 'Type-safe structured outputs from LLMs using Pydantic',
category: 'LLM & AI',
tags: ['instructor', 'pydantic', 'structured', 'validation'],
difficulty: 'intermediate'
},
// Network & APIs
{
title: 'grpcio-example.py',
Expand Down Expand Up @@ -142,10 +113,10 @@ const totalExamples = examples.length;
<div class="abstract">
<div class="abstract-title">Abstract</div>
<p>
This repository presents a comprehensive collection of Python examples demonstrating
modern development patterns, from cutting-edge LLM integrations to classic data processing.
Each example prioritizes security, type safety, and real-world applicability.
Built for developers who value clarity, efficiency, and getting things done.
A curated collection of practical Python code examples covering web APIs, data processing,
security tools, web scraping, and file manipulation. Each example is production-ready with
proper error handling, security considerations, and clear documentation. Built by a developer
who automates everything and believes good examples are better than lengthy tutorials.
</p>
</div>

Expand Down Expand Up @@ -204,17 +175,27 @@ cd python-examples
# Install dependencies (using uv)
uv sync --dev

# Run an example
# Run any example
cd python-examples
python openai_gpt-example.py</code></pre>
python requests-example.py</code></pre>

<h2>Why This Collection?</h2>
<ul style="font-family: var(--font-sans); font-size: 1rem; line-height: 2; margin-left: 2rem;">
<li><strong>Copy-Paste Ready</strong> - Working code you can use immediately</li>
<li><strong>Security Focused</strong> - Input validation, secure defaults, CodeQL verified</li>
<li><strong>Modern Python 3.12+</strong> - Using latest features and best practices</li>
<li><strong>Real-World Examples</strong> - Actual use cases, not toy demos</li>
<li><strong>No Fluff</strong> - Code first, explanations when needed</li>
</ul>

<h2>Features</h2>
<h2>Popular Examples</h2>
<ul style="font-family: var(--font-sans); font-size: 1rem; line-height: 2; margin-left: 2rem;">
<li><strong>Modern Python 3.12+</strong> - Leveraging latest language features</li>
<li><strong>Type Safety</strong> - Pydantic models and type hints throughout</li>
<li><strong>Security First</strong> - Input validation, secure defaults, CodeQL verified</li>
<li><strong>Production Ready</strong> - Error handling, logging, and best practices</li>
<li><strong>Well Documented</strong> - Clear docstrings and usage examples</li>
<li><strong>gRPC</strong> - Modern RPC framework with protocol buffers</li>
<li><strong>Flask</strong> - Web API with secure file uploads</li>
<li><strong>Scrapy</strong> - Web scraping at scale</li>
<li><strong>Tor Integration</strong> - Anonymous network access</li>
<li><strong>Shodan API</strong> - Internet device search and OSINT</li>
<li><strong>OpenCV</strong> - Computer vision and face detection</li>
</ul>

<footer class="site-footer">
Expand Down