How protossgp32/retrodev-docs works
Project type and purpose
• This is primarily a static documentation site (built with Quarto and published via GitHub Pages)
• It includes two self-hosted server projects under “projects/…” that illustrate deployment stacks for retro development tools
File structure
• Top-level:
– .github/workflows/quarto-publish.yml → CI pipeline
– docs/ → Quarto source files, custom extensions, images, styles
– projects/self-hosted-servers/parts-db → Docker Compose for parts-database
– projects/self-hosted-servers/pso-server → Dockerfile + executables (newserv, phosg, resource_dasm)
• README.md describes the overall goal: “easing deployment of software development environment for retro consoles”
README for technical stack
• Quarto (for docs)
• GitHub Actions (CI/CD)
• GitHub Pages (hosting the site)
• Docker Compose & individual Docker images (self-hosted servers)
Main components
a. Developer environment (local) – checks out repo, edits Quarto files, builds locally
b. Version control & CI/CD
• GitHub repo (with submodules)
• GitHub Actions workflow (quarto-publish.yml)
• Quarto build process
• Deployment to GitHub Pages
c. Documentation site
• Quarto source (docs/*.qmd, _extensions, styles.css)
• Static output (HTML + assets)
d. Self-hosted server deployments
1. Parts-DB
• Docker Compose stack:
– Database (PostgreSQL or similar)
– Web API service (e.g., a Python/Node app)
– Reverse proxy (optional)
2. PSO-server
• Dockerfile builds an image including:
– newserv (game server binary)
– phosg (utility library)
– resource_dasm (asset converter)
• Published to container registry (optional)
Relationships & interactions
• Developer → pushes commits → GitHub → triggers GitHub Actions
• Actions → runs Quarto build → produces static site → deploys to GitHub Pages
• End users → browse site on GitHub Pages → follow guides under /deploy-guides
• Guides reference the “projects” subfolder → user runs Docker Compose or docker build && docker run
• User ↔ self-hosted servers (HTTP/S requests to Parts-DB API or PSO server)
Architectural patterns & design principles
• Static site generation for docs (separation of content vs. runtime)
• CI/CD pipeline enforcing reproducible builds
• Containerization for server components (Docker Compose for multi-container stacks, single Dockerfile for custom servers)
• Modularity via Quarto extensions and Git submodules