Skip to content

Commit c0c0a53

Browse files
darshan-cppdarshan-cpp
committed
Complete notebook to PDF converter with professional UI and deployment config
1 parent b29d2d4 commit c0c0a53

23 files changed

Lines changed: 2831 additions & 1 deletion

‎.env.example‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
FLASK_ENV=development
2+
FLASK_DEBUG=True
3+
FLASK_APP=app.py
4+
MAX_FILE_SIZE=52428800

‎.github/workflows/deploy.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Notify Render on Push
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
notify:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Trigger Render Deploy
13+
run: |
14+
echo "✅ Code pushed to GitHub"
15+
echo "📦 Render will auto-deploy from this repository"
16+
echo "🔗 Set up auto-deploy at: https://render.com"
17+
echo ""
18+
echo "Steps:"
19+
echo "1. Go to render.com and sign in with GitHub"
20+
echo "2. Create Web Service from this repository"
21+
echo "3. Render will automatically deploy on every push"

‎.github/workflows/github-pages.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Deploy Static Demo to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
jobs:
15+
deploy:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v3
19+
20+
- name: Create docs folder
21+
run: |
22+
mkdir -p docs
23+
cp templates/index.html docs/index.html
24+
cp image.png docs/image.png
25+
26+
# Update paths for GitHub Pages
27+
sed -i 's|src="/image.png"|src="image.png"|g' docs/index.html
28+
29+
# Add warning banner about backend
30+
sed -i 's|<body>|<body><div style="position:fixed;top:0;left:0;right:0;background:#e57373;color:white;padding:12px;text-align:center;font-weight:600;z-index:9999;">⚠️ DEMO ONLY - PDF conversion requires backend server (not available on GitHub Pages)</div>|' docs/index.html
31+
32+
- name: Setup Pages
33+
uses: actions/configure-pages@v3
34+
35+
- name: Upload artifact
36+
uses: actions/upload-pages-artifact@v2
37+
with:
38+
path: './docs'
39+
40+
- name: Deploy to GitHub Pages
41+
id: deployment
42+
uses: actions/deploy-pages@v2

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
venv/
2+
__pycache__/
3+
*.pyc
4+
*.pyo
5+
*.pyd
6+
.Python
7+
*.so
8+
*.egg
9+
*.egg-info/
10+
dist/
11+
build/
12+
.env
13+
.vscode/
14+
.idea/
15+
*.log
16+
.DS_Store

‎Aptfile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
pandoc
2+
texlive-xetex
3+
texlive-fonts-recommended
4+
texlive-plain-generic

‎CHECKLIST.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Getting Started Checklist ✅
2+
3+
## Pre-Setup (System Level)
4+
5+
- [ ] Verify Python 3.8+ is installed
6+
```bash
7+
python3 --version
8+
```
9+
10+
- [ ] Install pip if not available
11+
```bash
12+
sudo apt-get install python3-pip
13+
```
14+
15+
- [ ] Install pandoc (required for PDF generation)
16+
```bash
17+
sudo apt-get update
18+
sudo apt-get install pandoc
19+
```
20+
21+
## Setup Phase
22+
23+
### Option A: Automated Setup (Recommended)
24+
25+
- [ ] Run setup script
26+
```bash
27+
chmod +x setup.sh
28+
./setup.sh
29+
```
30+
31+
- [ ] Skip to "Running the Application"
32+
33+
### Option B: Manual Setup
34+
35+
- [ ] Create virtual environment
36+
```bash
37+
python3 -m venv venv
38+
```
39+
40+
- [ ] Activate virtual environment
41+
```bash
42+
source venv/bin/activate
43+
```
44+
45+
- [ ] Install Python dependencies
46+
```bash
47+
pip install -r requirements.txt
48+
```
49+
50+
## Configuration
51+
52+
- [ ] Review configuration options (optional)
53+
```bash
54+
cp .env.example .env
55+
```
56+
57+
- [ ] Edit `.env` if needed (default settings work fine)
58+
59+
## Running the Application
60+
61+
- [ ] Ensure virtual environment is activated
62+
```bash
63+
source venv/bin/activate
64+
```
65+
66+
- [ ] Start the Flask application
67+
```bash
68+
python app.py
69+
```
70+
71+
- [ ] Verify app is running
72+
- Look for message: `Running on http://127.0.0.1:5000`
73+
74+
## Testing the Application
75+
76+
- [ ] Open web browser
77+
- [ ] Navigate to: http://localhost:5000
78+
- [ ] Verify UI loads properly (purple/blue gradient)
79+
- [ ] Check that upload area is visible
80+
81+
### Test Conversion
82+
83+
- [ ] Drag sample_notebook.ipynb to upload area
84+
```
85+
Sample file location: ./sample_notebook.ipynb
86+
```
87+
88+
- [ ] Click "Convert to PDF" button
89+
- [ ] Wait for conversion to complete
90+
- [ ] Verify PDF downloads automatically
91+
- [ ] Check PDF opens and displays correctly
92+
93+
## Alternative Testing (Command Line)
94+
95+
- [ ] Test API endpoint directly
96+
```bash
97+
curl -X POST -F "file=@sample_notebook.ipynb" \
98+
http://localhost:5000/api/convert -o test_output.pdf
99+
```
100+
101+
- [ ] Verify PDF was created
102+
```bash
103+
ls -lh test_output.pdf
104+
```
105+
106+
## Verification
107+
108+
- [ ] Web interface loads without errors ✅
109+
- [ ] Drag-and-drop area is visible ✅
110+
- [ ] File upload works ✅
111+
- [ ] Conversion completes successfully ✅
112+
- [ ] PDF downloads correctly ✅
113+
- [ ] Converted PDF opens properly ✅
114+
115+
## Documentation Review
116+
117+
- [ ] Read QUICK_START.md for quick reference
118+
- [ ] Review README.md for detailed information
119+
- [ ] Check SETUP.md for troubleshooting
120+
121+
## Troubleshooting Checklist
122+
123+
If something doesn't work:
124+
125+
- [ ] Virtual environment is activated?
126+
```bash
127+
source venv/bin/activate
128+
```
129+
130+
- [ ] All dependencies installed?
131+
```bash
132+
pip install -r requirements.txt
133+
```
134+
135+
- [ ] Pandoc installed?
136+
```bash
137+
which pandoc
138+
```
139+
140+
- [ ] Port 5000 is available?
141+
```bash
142+
lsof -i :5000
143+
```
144+
145+
- [ ] No syntax errors in code?
146+
```bash
147+
python -m py_compile app.py
148+
```
149+
150+
- [ ] Flask running properly?
151+
- Check console output for errors
152+
- Verify Flask version: `pip show Flask`
153+
154+
## Common Issues & Solutions
155+
156+
| Issue | Solution |
157+
|-------|----------|
158+
| `ModuleNotFoundError` | Run `pip install -r requirements.txt` |
159+
| `pandoc not found` | Run `sudo apt-get install pandoc` |
160+
| `Port 5000 in use` | Kill process: `lsof -ti :5000 \| xargs kill -9` |
161+
| `Permission denied setup.sh` | Run `chmod +x setup.sh` first |
162+
| Browser shows connection error | Ensure app.py is running |
163+
164+
## First Upload Tips
165+
166+
- [ ] Start with sample_notebook.ipynb
167+
- [ ] File should be max 50MB
168+
- [ ] Only .ipynb files are supported
169+
- [ ] Wait for progress bar to complete
170+
- [ ] PDF should download automatically
171+
172+
## Deactivate When Done
173+
174+
```bash
175+
deactivate
176+
```
177+
178+
## Next Steps After Verification
179+
180+
- [ ] Customize the application (optional)
181+
- [ ] Commit to git if needed
182+
- [ ] Share with team/users
183+
- [ ] Monitor usage and performance
184+
- [ ] Plan future enhancements
185+
186+
## Optional Customizations
187+
188+
- [ ] Change the port number in app.py
189+
- [ ] Modify UI styling in templates/index.html
190+
- [ ] Update max file size in app.py
191+
- [ ] Add custom error messages
192+
- [ ] Create custom PDF styling
193+
194+
## Maintenance
195+
196+
- [ ] Keep dependencies updated
197+
```bash
198+
pip install --upgrade -r requirements.txt
199+
```
200+
201+
- [ ] Monitor for security updates
202+
- [ ] Clean up temp files periodically
203+
- [ ] Review error logs
204+
205+
## Success! 🎉
206+
207+
Once all checkboxes are complete, your Jupyter Notebook to PDF Converter is:
208+
209+
✅ Installed
210+
✅ Configured
211+
✅ Running
212+
✅ Tested
213+
✅ Ready for use!
214+
215+
Enjoy converting notebooks to PDFs! 📓➜📄

0 commit comments

Comments
 (0)