From 79c632bc9fed8da638cef714359c2b61c199f090 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Fri, 20 May 2022 10:49:37 +0200 Subject: [PATCH] README: expand documentation of code generation --- README.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1aeac436..6b7df259 100644 --- a/README.md +++ b/README.md @@ -55,16 +55,28 @@ using `localhost`, and if you're not testing on `localhost` this stands out more. -## Generating the OpenAPI/Swagger API +## Generating Code -Some code is generated from the OpenAPI specs in -`pkg/api/flamenco-openapi.yaml`. The generated code is committed to Git, so that -after a checkout you shouldn't need to re-run the generator to build Flamenco. +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. -The JavaScript and Python generator is made in Java, so it requires a JRE/JDK to +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. + +- `addon/flamenco/manager/`: Python API for the Blender add-on. +- `pkg/api/*.gen.go`: Go API shared by Manager and Worker. +- `internal/**/mocks/*.gen.go`: Generated mocks for Go unit tests. +- `web/app/src/manager-api/`: JavaScript API for the web front-end. + + ## OpenAPI Commit Guidelines Typically a change to the OpenAPI definition consists of three steps, namely