Skip to content

Commit d7f4039

Browse files
Copilotnpv2k1
Copilot
and
npv2k1
committed
Add quick start guide and documentation index
Co-authored-by: npv2k1 <[email protected]>
1 parent b176347 commit d7f4039

File tree

2 files changed

+309
-0
lines changed

2 files changed

+309
-0
lines changed

‎docs/QUICK-START.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Quick Start Guide
2+
3+
Choose your preferred development method and get started in minutes!
4+
5+
## 🚀 Fastest Methods
6+
7+
### GitHub Codespaces (Zero Setup!)
8+
1. Click "Code" → "Codespaces" → "Create codespace on main"
9+
2. Wait ~2 minutes for setup
10+
3. Start coding!
11+
12+
**Best for:** Trying the project, contributing without local setup
13+
14+
---
15+
16+
### Docker Compose (Simple)
17+
```bash
18+
git clone https://github.com/pnstack/template-rust.git
19+
cd template-rust
20+
docker compose up
21+
```
22+
23+
**Best for:** Quick testing, isolated environments
24+
25+
---
26+
27+
### Nix (Reproducible)
28+
```bash
29+
git clone https://github.com/pnstack/template-rust.git
30+
cd template-rust
31+
nix develop
32+
cargo run
33+
```
34+
35+
**Best for:** Guaranteed reproducible builds, NixOS users
36+
37+
---
38+
39+
### Local Development (Traditional)
40+
```bash
41+
# Install Rust
42+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
43+
44+
# Clone and build
45+
git clone https://github.com/pnstack/template-rust.git
46+
cd template-rust
47+
cargo build --release
48+
```
49+
50+
**Best for:** Full control, native performance
51+
52+
---
53+
54+
## 📋 Common Commands
55+
56+
### Using Make (Recommended)
57+
```bash
58+
make help # Show all available commands
59+
make build # Build debug version
60+
make test # Run tests
61+
make clippy # Run linter
62+
make fmt # Format code
63+
make all # Format, lint, test, and build
64+
```
65+
66+
### Using Cargo
67+
```bash
68+
cargo build # Debug build
69+
cargo build --release # Optimized build
70+
cargo test # Run tests
71+
cargo clippy -- -D warnings # Lint
72+
cargo fmt # Format
73+
```
74+
75+
### Using Docker
76+
```bash
77+
docker build -t template-rust . # Build image
78+
docker run --rm template-rust --help # Show help
79+
docker run --rm -it template-rust tui # Interactive TUI
80+
```
81+
82+
### Using Docker Compose
83+
```bash
84+
docker compose up # Start app
85+
docker compose up dev # Development mode
86+
docker compose down # Stop services
87+
```
88+
89+
---
90+
91+
## 🎯 First Steps After Setup
92+
93+
1. **Run the application:**
94+
```bash
95+
cargo run -- --help
96+
```
97+
98+
2. **Try the TUI:**
99+
```bash
100+
cargo run -- tui
101+
```
102+
103+
3. **Add a todo:**
104+
```bash
105+
cargo run -- add "My first task"
106+
```
107+
108+
4. **List todos:**
109+
```bash
110+
cargo run -- list
111+
```
112+
113+
5. **Run tests:**
114+
```bash
115+
cargo test
116+
```
117+
118+
---
119+
120+
## 🔍 Need More Details?
121+
122+
- **Full setup instructions:** [SETUP.md](../SETUP.md)
123+
- **Usage examples:** [README.md](../README.md)
124+
- **CI/CD info:** [CI-CD.md](CI-CD.md)
125+
126+
---
127+
128+
## ❓ Troubleshooting
129+
130+
### "SQLite not found"
131+
```bash
132+
# Ubuntu/Debian
133+
sudo apt-get install libsqlite3-dev
134+
135+
# macOS
136+
brew install sqlite
137+
138+
# Nix/Codespaces - Already included!
139+
```
140+
141+
### "OpenSSL not found"
142+
```bash
143+
# Ubuntu/Debian
144+
sudo apt-get install libssl-dev pkg-config
145+
146+
# macOS
147+
brew install openssl
148+
149+
# Nix/Codespaces - Already included!
150+
```
151+
152+
### "Slow first build"
153+
This is normal! Cargo compiles all dependencies on first build.
154+
Subsequent builds are much faster (seconds instead of minutes).
155+
156+
### Docker permission issues
157+
```bash
158+
# Create data directory with proper permissions
159+
mkdir -p data
160+
chmod 777 data
161+
```
162+
163+
---
164+
165+
## 🎓 Learning Resources
166+
167+
### Rust Basics
168+
- [The Rust Book](https://doc.rust-lang.org/book/)
169+
- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)
170+
171+
### Project-Specific
172+
- Explore [src/](../src/) for code organization
173+
- Check [tests/](../tests/) for testing examples
174+
- Read [examples/](../examples/) for usage patterns
175+
176+
### Development Tools
177+
- [Cargo Book](https://doc.rust-lang.org/cargo/)
178+
- [Clippy Lints](https://rust-lang.github.io/rust-clippy/)
179+
- [Rustfmt Configuration](https://rust-lang.github.io/rustfmt/)
180+
181+
---
182+
183+
## 💡 Tips
184+
185+
1. **Use rust-analyzer**: Best IDE support for Rust
186+
2. **Run clippy often**: Catches bugs early
187+
3. **Format before commit**: `cargo fmt` or `make fmt`
188+
4. **Test frequently**: `cargo test` or `make test`
189+
5. **Use `--release` for production**: Much faster
190+
191+
---
192+
193+
## 🤝 Contributing
194+
195+
Ready to contribute?
196+
197+
1. Fork the repository
198+
2. Create a branch: `git checkout -b feature/my-feature`
199+
3. Make changes
200+
4. Test: `make all`
201+
5. Commit: `git commit -m "Add feature"`
202+
6. Push: `git push origin feature/my-feature`
203+
7. Open a Pull Request
204+
205+
---
206+
207+
## 📞 Getting Help
208+
209+
- 📖 Read the [full docs](../README.md)
210+
- 🐛 [Open an issue](https://github.com/pnstack/template-rust/issues)
211+
- 💬 Check [existing issues](https://github.com/pnstack/template-rust/issues?q=is%3Aissue)
212+
213+
---
214+
215+
**Happy coding! 🦀**

‎docs/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Documentation
2+
3+
Welcome to the template-rust documentation!
4+
5+
## 📚 Available Documentation
6+
7+
### Getting Started
8+
- **[Quick Start Guide](QUICK-START.md)** - Get up and running in minutes with your preferred method
9+
10+
### Setup & Configuration
11+
- **[Setup Guide](../SETUP.md)** - Comprehensive setup instructions for all environments
12+
- Local development
13+
- Docker & Docker Compose
14+
- Nix & Nix Flakes
15+
- GitHub Codespaces & Devcontainer
16+
17+
### Development
18+
- **[CI/CD Documentation](CI-CD.md)** - Complete guide to our GitHub Actions workflows
19+
- CI workflow (build, test, lint)
20+
- Security auditing
21+
- Release automation
22+
- Docker builds
23+
24+
### Usage
25+
- **[Main README](../README.md)** - Project overview, features, and usage examples
26+
27+
## 🎯 Quick Links
28+
29+
### For Contributors
30+
1. [QUICK-START.md](QUICK-START.md) - Choose your setup method
31+
2. [../SETUP.md](../SETUP.md) - Detailed environment setup
32+
3. [CI-CD.md](CI-CD.md) - Understand our automated workflows
33+
34+
### For Users
35+
1. [../README.md](../README.md) - Learn how to use the application
36+
2. [QUICK-START.md](QUICK-START.md) - Quick reference for common tasks
37+
38+
### For Maintainers
39+
1. [CI-CD.md](CI-CD.md) - Managing workflows and releases
40+
2. [../SETUP.md](../SETUP.md) - Supporting different development environments
41+
42+
## 🔧 Configuration Files Reference
43+
44+
### Docker
45+
- `/Dockerfile` - Multi-stage Docker build
46+
- `/docker-compose.yml` - Development and production services
47+
- `/.dockerignore` - Build optimization
48+
49+
### Nix
50+
- `/flake.nix` - Nix flakes configuration
51+
- `/shell.nix` - Traditional Nix shell
52+
- `/.envrc` - Direnv integration
53+
54+
### Development Environment
55+
- `/.devcontainer/devcontainer.json` - VS Code devcontainer config
56+
- `/Makefile` - Common development commands
57+
58+
### CI/CD
59+
- `/.github/workflows/ci.yml` - Build, test, lint
60+
- `/.github/workflows/security.yml` - Security audits
61+
- `/.github/workflows/release.yml` - Automated releases
62+
- `/.github/workflows/docker.yml` - Docker builds
63+
64+
## 📖 Documentation Standards
65+
66+
When contributing documentation:
67+
68+
1. **Be Clear**: Use simple language and examples
69+
2. **Be Concise**: Respect the reader's time
70+
3. **Be Complete**: Cover edge cases and troubleshooting
71+
4. **Use Examples**: Show, don't just tell
72+
5. **Keep Updated**: Update docs when code changes
73+
74+
## 🤝 Contributing to Docs
75+
76+
Found an issue or want to improve the documentation?
77+
78+
1. Check if there's an [existing issue](https://github.com/pnstack/template-rust/issues)
79+
2. Open a new issue describing the problem
80+
3. Submit a PR with improvements
81+
82+
Good documentation helps everyone! 🎉
83+
84+
## 📞 Questions?
85+
86+
If you can't find what you're looking for:
87+
88+
1. Check all documentation files listed above
89+
2. Search [existing issues](https://github.com/pnstack/template-rust/issues)
90+
3. Open a [new issue](https://github.com/pnstack/template-rust/issues/new) with your question
91+
92+
---
93+
94+
**Thank you for reading! 🦀**

0 commit comments

Comments
 (0)