Welcome to Easy8 Developer Documentation!
In the following articles you will get familiar with the following:
- How to set up your machine
- How to work with RYSes
- How to contribute to the codebase
- How to properly release new RYSes and features
- Feature guides
- API reference
- GraphQL reference
- AI developer tools and integrations
About this documentation & contribution
This repository contains first-class developer documentation maintained alongside the source code using MkDocs.
The goal is to keep documentation:
- close to the code,
- versioned together with changes,
- easy to contribute to,
- and reliable for onboarding and day-to-day development.
Why MkDocs
MkDocs is used as the documentation engine because it fits internal, code-centric documentation best:
- Markdown + Git workflow (no separate tooling or UI)
- Documentation evolves in the same merge requests as code
- Versioned naturally by branches and releases
- Easy local preview
- CI-friendly and reproducible
- Supports narrative docs (onboarding, architecture, guides)
- Can embed OpenAPI docs when needed (Swagger UI / ReDoc)
Documentation Structure
Getting Started
- Initial Setup - Set up your development environment
- Repository Structure - Understanding the codebase organization
- Contributing - How to contribute to the project
AI
Backend Development
- Backend Best Practices
- Backend Code Style
- Backend Testing
- Backend Tooling
- Docker Setup
- Services Architecture
- Let It Be Testing
Backend Features
- Controllers
- Models
- GraphQL Implementation
- Easy Pages
- Easy Queries
- Journals
- JWT Tokens
- Migrations
- Feature Toggle
- Feature Toggle (Legacy)
BlueSpice Integration
Frontend Development
- Frontend Introduction
- Frontend Styling
- Frontend Code Style
- Frontend Structure and Architecture
- Frontend Dates and Timezones
- Frontend Testing
- Legacy Frontend HTML Patterns (Deprecated)
- Frontend Forms (Deprecated)
- Frontend Design System
- Frontend Codegen
- Vuetify Styles (Deprecated)
Frontend Standards
- Components Standards
- Composables Standards
- Constants Standards
- GraphQL Standards
- REST Standards
- State Management Standards
- UTM Tracking Standards
- Utils Standards
APIs
Testing
RYS Management
- Getting Started with RYS
- RYS Management
- RYSPEC
- Moving a RYS Repository with History
- Generator
- Patch Management
- Feature Toggler
Release & Contribution
Feature Guides
Easy8 Specific
- Easy8 Terminology
- Server Requirements
- Package Repositories
- Support and Tools
- User Testing
- RubyMine Plugins
Zeitwerk Support
Upgrade
Major Releases
Other Resources
Getting started with MkDocs
- Install documentation dependencies
make docs-deps
This installs MkDocs and related tools using uv in an isolated environment. - Run documentation locally
make docs-serve
Then open:
http://127.0.0.1:8001 - Build documentation (CI / verification)
make docs-build
This performs a strict build and fails on broken links or invalid configuration.
Writing documentation
- All documentation lives in docs/
- Use Markdown (.md)
- Add a blank line before lists, code blocks, and admonitions
- Keep content focused on:
- onboarding
- architecture
- guides & how-tos
- APIs & references
- runbooks
Docs should be updated together with code changes whenever relevant.
OpenAPI documentation
OpenAPI specifications is be embedded into MkDocs pages using: Swagger UI (interactive)
This keeps API reference close to the rest of the developer documentation without making APIs the only focus.
Contributing
- Treat documentation changes like code changes
- Prefer small, incremental updates
- Update docs in the same PR as the related code
- Broken docs should fail CI
Philosophy
- Documentation is part of the product.
- If it matters to developers, it belongs in the repository.