🐍 Python 示例
展示 My Docs 在 Python 项目中的实际应用案例。
基础示例
示例 1：简单文档项目
# docs/mkdocs.yml
site_name: My Project
nav:
- Home: index.md
- About: about.md
# docs/index.md
# 欢迎来到 My Project
这是一个示例项目文档。
示例 2：带代码高亮的文档
# API 使用示例
## 基本用法
```python
import requests
def get_data():
response = requests.get('https://api.example.com/data')
return response.json()
```
## 高级用法
```python
class DataProcessor:
def __init__(self, api_url):
self.api_url = api_url
def process(self):
data = self.get_data()
return self.analyze(data)
```
实战项目示例
项目结构
my-project/
├── docs/
│ ├── mkdocs.yml
│ ├── index.md
│ ├── guide/
│ │ ├── installation.md
│ │ └── usage.md
│ └── api/
│ └── reference.md
├── src/
│ └── my_project/
└── tests/
完整配置示例
# mkdocs.yml
site_name: My Awesome Project
site_url: https://my-project.com
repo_url: https://github.com/user/my-project
theme:
name: material
palette:
primary: teal
accent: pink
nav:
- 首页: index.md
- 指南:
- 安装: guide/installation.md
- 使用: guide/usage.md
- API 参考: api/reference.md
markdown_extensions:
- pymdownx.highlight
- pymdownx.superfences
高级功能示例
多标签代码示例
# 多语言示例
=== "Python"
```python
def hello_python():
print("Hello from Python!")
```
=== "JavaScript"
```javascript
function helloJS() {
console.log("Hello from JavaScript!");
}
```
=== "Bash"
```bash
echo "Hello from Bash!"
```
数学公式支持
图表示例
集成示例
与 Jupyter Notebook 集成
API 文档生成
# 自动生成 API 文档示例
def generate_api_docs(module_path):
"""自动生成模块的 API 文档"""
import inspect
import os
docs = []
for name, obj in inspect.getmembers(module_path):
if inspect.isclass(obj) or inspect.isfunction(obj):
docs.append(f"## {name}\n\n{obj.__doc__}\n")
return "\n".join(docs)
部署示例
GitHub Actions 自动化部署
# .github/workflows/deploy.yml
name: Deploy Docs
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
Vercel 部署配置
// vercel.json
{
"version": 2,
"builds": [
{
"src": "mkdocs.yml",
"use": "@vercel/static-build"
}
],
"routes": [
{
"src": "/(.*)",
"dest": "/site/$1"
}
]
}
最佳实践示例
文档组织结构
docs/
├── overview/ # 项目概述
├── getting-started/ # 快速开始
├── guides/ # 使用指南
├── api/ # API 参考
├── examples/ # 代码示例
└── faq/ # 常见问题
内容质量检查
# docs/check_quality.py
import os
import re
def check_markdown_quality(filepath):
"""检查 Markdown 文件质量"""
with open(filepath, 'r', encoding='utf-8') as f:
content = f.read()
issues = []
# 检查标题层级
if not re.search(r'^# ', content, re.MULTILINE):
issues.append("缺少一级标题")
# 检查代码块
code_blocks = re.findall(r'```.*?```', content, re.DOTALL)
if not code_blocks:
issues.append("建议添加代码示例")
return issues
性能优化示例
构建优化配置
# mkdocs.yml
extra_css:
- styles/optimized.css
extra_javascript:
- js/optimized.js
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
- pymdownx.superfences
图片优化
# 优化图片使用
<!-- 使用 WebP 格式 -->
{ loading=lazy }
<!-- 响应式图片 -->
<img srcset="
images/example-320w.jpg 320w,
images/example-640w.jpg 640w,
images/example-1024w.jpg 1024w
" sizes="(max-width: 600px) 100vw, 50vw"
src="images/example-640w.jpg" alt="示例">
扩展功能示例
自定义插件
# plugins/custom_plugin.py
from mkdocs.plugins import BasePlugin
class CustomPlugin(BasePlugin):
def on_page_markdown(self, markdown, page, config, files):
# 自定义 Markdown 处理
return markdown.replace('{{version}}', '1.0.0')
主题定制
/* styles/extra.css */
:root {
--md-primary-fg-color: #2E7D32;
--md-accent-fg-color: #00C853;
}
.md-header {
background: linear-gradient(45deg, #2E7D32, #4CAF50);
}
查看更多示例: 完整项目示例