How ba-calderonmorales/my-life-as-a-dev works
Project type and purpose
• This is a docs-as-code static site generator built with MkDocs (Material theme), extended by:
• Custom Python plugins (mkdocs_plugins/ai_plugin.py, versioning plugin)
• A Rust-based CLI tool (scripts/doc-cli.rs, bump-version.rs, etc.) wrapped by doc-cli.sh
• GitHub Actions → GitHub Pages for CI/CD deployments
• Browser-based AI Playground calling the OpenAI REST API
File structure
• Content sources: docs/ (Markdown, assets, theme overrides)
• Build config: mkdocs.yml, requirements.txt, setup.py
• Plugins: mkdocs_plugins/ (Python modules for AI integration, versioning)
• CLI tooling: scripts/ (Rust Cargo projects), doc-cli.sh
• CI/CD: .github/workflows/github_pages.yml, Dependabot, test workflows
• Hosting artifacts: generated site/ directory → published via GitHub Pages
Key sections from the README
• Local dev: Python venv → pip install -r requirements.txt → mkdocs serve (with PYTHONPATH)
• AI plugin: build-time OpenAI integration (via env var or .env)
• Rust CLI: startup, bump-version, deploy commands
• CI: on push → compile Rust → mkdocs build → mike versioning → deploy to GitHub Pages
• Browser AI Demo: JS widgets (docs/assets/js/components/aiPlayground) invoke OpenAI directly
Main components & interactions (to model
a. Developer Local Environment
• Python interpreter + MkDocs + custom Python plugins
• Rust toolchain (Cargo) + doc-cli.sh wrapper
• .env / environment variables for OpenAI key
b. CI/CD Pipeline (GitHub Actions)
• Checkout source → compile Rust → install Python deps → mkdocs build --verbose → mike versioning → deploy to GitHub Pages
c. Static Site Hosting
• GitHub Pages serves the generated site/ directory
d. End-User Browser
• Requests HTML/CSS/JS assets
• Renders interactive pages (AI-Playground widgets, particle backgrounds, etc.)
• For AI demo, front-end JS calls the OpenAI REST API using the user’s provided API key
e. OpenAI API
• External service for run-time JS calls (Playground)
• Also used at build time by Python AI plugin if configured
Architectural patterns & principles
• Static site generation (SSG) with plugin-based extension (Python plugin hook points)
• Docs-as-code: Markdown source under version control, repeatable build
• Micro-tooling: Rust CLI implements SOLID, DRY, error handling, interactive menus
• CI/CD as code: workflow files in .github/workflows automate build/test/deploy
• Separation of concerns: content (docs/), build logic (mkdocs plugins), deployment (GitHub Actions)
Final checklist
• essential modules: docs/, mkdocs_plugins/, scripts/, GitHub Actions, GitHub Pages, Browser, OpenAI