Skip to content

Commit 2d0ea73

Browse files
yoanbernabeuyoanbernabeu
authored
Merge pull request #18 from yoanbernabeu/17-set-up-project-documentation-with-mkdocs
17 set up project documentation with mkdocs
2 parents 9ecc151 + 26679d1 commit 2d0ea73

File tree

8 files changed

+455
-0
lines changed

8 files changed

+455
-0
lines changed

‎.docs/docs/index.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# OpenStreamPoll Documentation
2+
3+
## Welcome to OpenStreamPoll
4+
5+
OpenStreamPoll is an open-source live polling platform specifically designed for streamers. It enables real-time audience engagement through interactive polls, featuring instant results and seamless integration with popular streaming tools.
6+
7+
## Quick Start
8+
9+
=== "Quick Install"
10+
```bash
11+
git clone https://github.com/yoanbernabeu/OpenStreamPoll.git
12+
cd OpenStreamPoll
13+
make deploy
14+
```
15+
16+
=== "Docker"
17+
```bash
18+
docker run -d -p 80:80 \
19+
-e SERVER_NAME=:80 \
20+
-e APP_ENV=prod \
21+
--name openstreampoll \
22+
yoanbernabeu/openstreampoll:latest
23+
```
24+
25+
=== "Development"
26+
```bash
27+
git clone https://github.com/yoanbernabeu/OpenStreamPoll.git
28+
cd OpenStreamPoll
29+
make first-install
30+
```
31+
32+
## Key Features
33+
34+
- **Live Polling System**
35+
- Create instant polls
36+
- Real-time results
37+
- Multiple choice questions
38+
39+
- **Stream Integration**
40+
- Native OBS integration
41+
- Customizable overlays
42+
- QR code display
43+
44+
- **Easy Administration**
45+
- User-friendly interface
46+
- Poll management
47+
- Results tracking
48+
49+
## Project Overview
50+
51+
OpenStreamPoll is built with:
52+
53+
- PHP 8.3 with Symfony 7.2
54+
- Alpine.js & HTMX
55+
- Tailwind CSS with DaisyUI
56+
- Docker & FrankenPHP
57+
58+
For detailed information, check out:
59+
60+
- [Installation Guide](installation.md)
61+
- [Usage Guide](usage.md)
62+
- [GitHub Repository](https://github.com/yoanbernabeu/OpenStreamPoll)

‎.docs/docs/installation.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Installation
2+
3+
This page details the different methods for installing OpenStreamPoll.
4+
5+
## Prerequisites
6+
7+
Before starting the installation, make sure you have:
8+
9+
- PHP 8.3 or higher
10+
- Composer
11+
- Symfony CLI
12+
- SQLite
13+
- Make
14+
- Docker (recommended)
15+
16+
## 1. Production Deployment with Make (Recommended)
17+
18+
### Quick Steps
19+
20+
```bash
21+
# Clone the repository
22+
git clone https://github.com/yoanbernabeu/OpenStreamPoll.git
23+
cd OpenStreamPoll
24+
25+
# Launch deployment
26+
make deploy
27+
```
28+
29+
### Process Details
30+
31+
The `make deploy` command will automatically:
32+
33+
1. Create a `compose.prod.yaml` file from the template
34+
2. Ask for your domain name
35+
3. Start Docker containers
36+
4. Create and configure the database
37+
5. Create the administrator account
38+
39+
## 2. Manual Production Deployment
40+
41+
If you prefer to control each step:
42+
43+
```bash
44+
# Clone the repository
45+
git clone https://github.com/yoanbernabeu/OpenStreamPoll.git
46+
cd OpenStreamPoll
47+
48+
# Create production configuration
49+
cp compose.yaml compose.prod.yaml
50+
51+
# Configure domain in compose.prod.yaml
52+
# SERVER_NAME=yourdomain.com (use :80 without SSL)
53+
54+
# Start services
55+
docker compose -f compose.prod.yaml up -d
56+
57+
# Create database
58+
docker compose -f compose.prod.yaml exec openstreampoll php bin/console doctrine:database:create
59+
60+
# Run migrations
61+
docker compose -f compose.prod.yaml exec openstreampoll php bin/console doctrine:migrations:migrate --no-interaction
62+
63+
# Create admin user
64+
docker compose -f compose.prod.yaml exec openstreampoll php bin/console app:create-user <username> <password>
65+
```
66+
67+
## 3. Development Installation
68+
69+
For local development with hot-reload:
70+
71+
```bash
72+
# Initial installation
73+
make first-install
74+
75+
# Normal startup
76+
make start
77+
78+
# Useful commands
79+
make stop # Stop server
80+
make reset-db # Reset database
81+
make tests # Run tests
82+
make before-commit # Pre-commit checks
83+
```
84+
85+
## 4. Quick Local Testing with Docker
86+
87+
For rapid testing:
88+
89+
```bash
90+
# Start container
91+
docker run -d -p 80:80 \
92+
-e SERVER_NAME=:80 \
93+
-e APP_ENV=prod \
94+
--name openstreampoll \
95+
yoanbernabeu/openstreampoll:latest
96+
97+
# Database setup
98+
docker exec openstreampoll php bin/console doctrine:database:create
99+
docker exec openstreampoll php bin/console doctrine:migrations:migrate --no-interaction
100+
docker exec openstreampoll php bin/console app:create-user <username> <password>
101+
```
102+
103+
The application will be accessible at `http://localhost`
104+
105+
## Troubleshooting
106+
107+
### Common Errors
108+
109+
1. **Permission Issues**
110+
- Check write permissions on the `var/` directory
111+
- Use `chmod -R 777 var/` if needed
112+
113+
2. **Database Errors**
114+
- Verify SQLite is installed
115+
- Ensure database directory is writable
116+
117+
3. **Docker Container Issues**
118+
- Check logs with `docker compose logs`
119+
- Ensure ports are not already in use
120+
121+
### Support
122+
123+
If you encounter problems:
124+
125+
1. Check [GitHub issues](https://github.com/yoanbernabeu/OpenStreamPoll/issues)
126+
2. Create a new issue if needed
127+
3. For security concerns, contact the maintainer directly

‎.docs/docs/stylesheets/extra.css‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
:root {
2+
--md-primary-fg-color: #661AE6;
3+
--md-primary-fg-color--light: #8B5CF6;
4+
--md-primary-fg-color--dark: #4C1D95;
5+
--md-accent-fg-color: #8B5CF6;
6+
}
7+
8+
[data-md-color-scheme="slate"] {
9+
--md-hue: 232;
10+
--md-default-bg-color: #1f2937;
11+
--md-default-fg-color: #f8fafc;
12+
--md-default-fg-color--light: #e2e8f0;
13+
--md-code-bg-color: #111827;
14+
--md-code-fg-color: #e2e8f0;
15+
--md-typeset-a-color: #8B5CF6;
16+
}
17+
18+
.md-header {
19+
background-color: #111827;
20+
}
21+
22+
.md-nav__link:hover {
23+
color: #8B5CF6 !important;
24+
}
25+
26+
.md-typeset code {
27+
background-color: #1f2937;
28+
border: 1px solid #374151;
29+
border-radius: 0.2rem;
30+
}
31+
32+
.md-typeset pre > code {
33+
background-color: #111827;
34+
}
35+
36+
.md-nav__item .md-nav__link--active {
37+
color: #8B5CF6;
38+
}
39+
40+
.md-typeset .admonition {
41+
border-left: 0.2rem solid #8B5CF6;
42+
background-color: #111827;
43+
}
44+
45+
/* Styles pour les onglets */
46+
.md-tabs {
47+
background-color: #111827;
48+
}
49+
50+
.tabbed-set {
51+
border-radius: 0.5rem;
52+
overflow: hidden;
53+
margin: 1.5em 0;
54+
}
55+
56+
.tabbed-set .tabbed-content {
57+
padding: 1rem;
58+
background-color: #1f2937;
59+
border: 1px solid #374151;
60+
border-top: none;
61+
}
62+
63+
.tabbed-set .tabbed-labels {
64+
background-color: #111827;
65+
border-bottom: 1px solid #374151;
66+
}
67+
68+
.tabbed-set .tabbed-labels > label {
69+
color: #e2e8f0;
70+
padding: 0.5rem 1rem;
71+
font-weight: 600;
72+
}
73+
74+
.tabbed-set .tabbed-labels > label:hover {
75+
color: #8B5CF6;
76+
}
77+
78+
.tabbed-set .tabbed-labels > input:checked + label {
79+
color: #8B5CF6;
80+
border-bottom: 2px solid #8B5CF6;
81+
}
82+
83+
/* Active tab content */
84+
.tabbed-block {
85+
display: none;
86+
}
87+
88+
.tabbed-block.active {
89+
display: block;
90+
}

‎.docs/docs/usage.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Usage Guide
2+
3+
## Creating Polls
4+
5+
=== "Basic Creation"
6+
1. Log in to the admin panel
7+
2. Click "New Poll"
8+
3. Enter your question
9+
4. Add answer options
10+
5. Click "Create"
11+
12+
=== "Advanced Options"
13+
- Set poll duration
14+
- Configure voting limits
15+
- Enable/disable features
16+
- Save as draft
17+
18+
=== "Management"
19+
- Edit existing polls
20+
- View results
21+
- Close/reopen polls
22+
- Delete polls
23+
24+
## OBS Integration
25+
26+
=== "Poll Display"
27+
1. Add Browser Source in OBS
28+
2. Enter URL: `https://yourdomain.com/obs`
29+
3. Set dimensions (1920x1080 recommended)
30+
4. Position as needed
31+
32+
=== "QR Code"
33+
1. Add Browser Source
34+
2. URL: `https://yourdomain.com/obs/qr`
35+
3. Position in corner of stream
36+
4. Viewers scan to participate
37+
38+
=== "Admin Panel"
39+
1. Open OBS Docks menu
40+
2. Add Custom Browser Dock
41+
3. URL: `https://yourdomain.com/admin`
42+
4. Manage polls directly from OBS
43+
44+
## Best Practices
45+
46+
=== "Poll Creation"
47+
- Keep questions clear
48+
- Limit options (max 5)
49+
- Use appropriate timing
50+
- Test before going live
51+
52+
=== "Stream Integration"
53+
- Position polls strategically
54+
- Use consistent styling
55+
- Test visibility on all layouts
56+
- Consider mobile viewers
57+
58+
=== "Engagement"
59+
- Announce polls clearly
60+
- Give adequate voting time
61+
- Discuss results live
62+
- Thank participants

0 commit comments

Comments
 (0)