From 65f391183eceb0b3a2e2127a4abd6f01f6a0ea0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Mon, 30 Jun 2025 11:01:13 +0200
Subject: [PATCH] Add `install-generators` make target and improve
 documentation

Add Make target `install-generators` as alias for `mage installGenerators`
and update the documentation for it.
---
 Makefile                                      |  3 ++
 .../development/generating-code/_index.md     | 32 ++++++++++++++++---
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index c26b9e3b..35b56012 100644
--- a/Makefile
+++ b/Makefile
@@ -93,6 +93,9 @@ db-migrate-down:
 webapp-static: buildtool
 	"${BUILDTOOL_PATH}" webappStatic
 
+install-generators: buildtool
+	"${BUILDTOOL_PATH}" installGenerators
+
 generate: buildtool
 	"${BUILDTOOL_PATH}" generate
 
diff --git a/web/project-website/content/development/generating-code/_index.md b/web/project-website/content/development/generating-code/_index.md
index 5bc054a8..b1436123 100644
--- a/web/project-website/content/development/generating-code/_index.md
+++ b/web/project-website/content/development/generating-code/_index.md
@@ -7,13 +7,37 @@ Some code (Go, Python, JavaScript) is generated from the OpenAPI specs in
 `pkg/api/flamenco-openapi.yaml`. There are also Go files generated to create
 mock implementations of interfaces for unit testing purposes.
 
+## Installing the Code Generators
+
+There are three code generators used by Flamenco:
+
+- [`oapi-codegen`][oapi-codegen] for the OpenAPI server & client in Go.
+- [`mockgen`][mockgen] for generating mocks for tests in Go.
+- [`openapi-codegen`][openapi-codegen] for the OpenAPI clients in Python and JavaScript.
+
+[oapi-codegen]: https://github.com/deepmap/oapi-codegen/cmd/oapi-codegen
+[mockgen]: https://github.com/golang/mock/mockgen
+[openapi-codegen]: https://openapi-generator.tech/
+
+The first two generators can be installed with either of these commands:
+
+```bash
+# Simplest way to install the Go generators:
+$ go run mage.go installGenerators
+
+# Faster to re-run than the above, but does require Make:
+$ make install-generators
+```
+
+`openapi-codegen` is bundled with the Flamenco sources, but does need a Java
+runtime environment to be installed. On Ubuntu Linux, `sudo apt install
+default-jre-headless` should be enough.
+
+## Committing Generated Code
+
 **Generated code is committed to Git**, so that after a checkout you shouldn't
 need to re-run the generator to build Flamenco.
 
-The JavaScript & Python generator is made in Java, so it requires a JRE/JDK to
-be installed. On Ubuntu Linux, `sudo apt install default-jre-headless` should be
-enough.
-
 The following files & directories are generated. Generated directories are
 completely erased before regeneration, so do not add any files there manually.