Real-World Example

The best way to understand makefile2doc is to see it in action. Below is the Result (the generated Markdown) and the Input (the raw Makefile) from our internal test suite.

Makefile Documentation

Auto-generated by makefile2doc

Cheat Sheet

Workflow Graph

flowchart LR
    subgraph Development_Environnement[Development Environnement]
        up(up)
        down(down)
        logs(logs)
        shell-back(shell-back)
        shell-front(shell-front)
        shell-db(shell-db)
    end
    style Development_Environnement fill:transparent,stroke-dasharray: 5 5
    classDef cat0 fill:#E1F5FE,stroke:#01579B,stroke-width:2px,color:#000;
    class up cat0
    class down cat0
    class logs cat0
    class shell-back cat0
    class shell-front cat0
    class shell-db cat0
    subgraph Setup_&_Initialization[Setup & Initialization]
        install-back(install-back)
        install-front(install-front)
        install(install)
    end
    style Setup_&_Initialization fill:transparent,stroke-dasharray: 5 5
    classDef cat1 fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px,color:#000;
    class install-back cat1
    class install-front cat1
    class install cat1
    subgraph Database[Database]
        migrate(migrate)
        seed(seed)
    end
    style Database fill:transparent,stroke-dasharray: 5 5
    classDef cat2 fill:#FFF3E0,stroke:#E65100,stroke-width:2px,color:#000;
    class migrate cat2
    class seed cat2
    subgraph Code_Quality[Code Quality]
        test-back(test-back)
        lint-front(lint-front)
        lint-back(lint-back)
        fix-front(fix-front)
        fix-back(fix-back)
        lint(lint)
        fix(fix)
    end
    style Code_Quality fill:transparent,stroke-dasharray: 5 5
    classDef cat3 fill:#F3E5F5,stroke:#4A148C,stroke-width:2px,color:#000;
    class test-back cat3
    class lint-front cat3
    class lint-back cat3
    class fix-front cat3
    class fix-back cat3
    class lint cat3
    class fix cat3
    subgraph Deployment[Deployment]
        build-front(build-front)
        deploy(deploy)
    end
    style Deployment fill:transparent,stroke-dasharray: 5 5
    classDef cat4 fill:#FFEBEE,stroke:#B71C1C,stroke-width:2px,color:#000;
    class build-front cat4
    class deploy cat4

    logs --> up
    shell-back --> up
    shell-front --> up
    shell-db --> up
    install --> install-back
    install --> install-front
    migrate --> up
    migrate --> install
    seed --> migrate
    test-back --> install
    lint-front --> install-front
    lint-back --> install-back
    fix-front --> install-front
    fix-back --> install-back
    lint --> lint-front
    lint --> lint-back
    fix --> fix-front
    fix --> fix-back
    build-front --> install
    deploy --> build-front
    deploy --> migrate

Section Details

Development Environnement

Setup & Initialization

Database

Code Quality

Deployment

2. The Input (Makefile)

This is the source Makefile using The Convention.

Pro Tip: We recommend using visual separators (like the # === lines below) to clearly delimit your categories. This keeps the raw file readable for humans, while the parser simply ignores them.

# ==============================================================================
## @category Development Environnement
# ==============================================================================

## @description Start the full development environment (Docker)
## @env PORT
up:
	# docker compose up -d

## @description Stop all containers
down:
	# docker compose down

## @description Show live logs for all services
## @depends up
logs:
	# docker compose logs -f

## @description Open a shell inside the PHP container (Laravel)
## @depends up
shell-back:
	# docker compose exec app bash

## @description Open a shell inside the Node.js container
## @depends up
shell-front:
	# docker compose exec app bash

## @description Open a shell inside the PostgreSQL container
## @depends up
shell-db:
	# docker compose exec app bash

# ==============================================================================
## @category Setup & Initialization
# ==============================================================================

## @description Install backend (Composer)
install-back:
	# docker compose run --rm app composer install

## @description Install frontend (NPM) dependencies
install-front:
	# docker compose run --rm app npm install

## @description Run both backend and frontend installations
## @depends install-back, install-front
install: install-back install-front

# ==============================================================================
## @category Database
# ==============================================================================

## @description Run database migrations
## @depends up, install
migrate:
	# docker compose exec app php artisan migrate

## @description Reset the DB and run seeds (Test data) \n Warning: This deletes all data!
## @depends migrate
## @env SEED_CLASS
seed:
	# docker compose exec app php artisan migrate:refresh --seed

# ==============================================================================
## @category Code Quality
# ==============================================================================

## @description Run unit tests (Pest/PHPUnit)
## @depends install
test-back:
	# docker-compose exec app php artisan test

## @description Lint frontend code (ESLint)
## @depends install-front
lint-front:
	# docker compose exec app npm run lint

## @description Lint backend code (PHP-CS-Fixer dry-run)
## @depends install-back
lint-back:
	# docker compose exec app php-cs-fixer

## @description Fix frontend code style and format
## @depends install-front
fix-front:
	# docker compose exec app npm run lint-fix && npm run format

## @description Fix backend code style
## @depends install-back
fix-back:
	# docker compose exec app php-cs-fixer --fix

## @description Run all linters (front & back)
## @depends lint-front, lint-back
lint: lint-front lint-back

## @description Fix all code style issues (front & back)
## @depends fix-front, fix-back
fix: fix-front fix-back

# ==============================================================================
## @category Deployment
# ==============================================================================

## @description Compile Frontend assets (Vite/Mix)
## @depends install
build-front:
	# npm run build

## @description Deploy to Production \n 1. Build frontend assets \n 2. Optimize Laravel cache \n 3. Run migrations force
## @depends build-front, migrate
## @env APP_KEY, SSH_USER
deploy:
	# git pull
	# docker compose exec app php artisan config:cache
	# docker compose exec app php artisan migrate --force