docs: document the generate --config option

Author: omer-cengel

README.md

@@ -72,9 +72,19 @@ java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar generate   # compile sqlcj.yaml into Java
 java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar --help     # list the commands
 ```
 
-`generate` reads `sqlcj.yaml` from the directory it is run in. It exits with
-status `0` on success, and with status `1` after printing one diagnostic for
-invalid configuration, an unreadable source, or a query it cannot compile.
+`generate` reads `sqlcj.yaml` from the directory it is run in.
+`--config <path>` names another configuration file, so generation can run from
+any working directory:
+
+```bash
+java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar generate --config ../project/sqlcj.yaml
+```
+
+A relative `--config` value is resolved against the directory the command is
+run in, while the relative paths inside the file stay relative to the file's own
+directory. `generate` exits with status `0` on success, and with status `1`
+after printing one diagnostic for invalid configuration, an unreadable source,
+or a query it cannot compile.
 
 ## Getting started
 

docs/configuration.md

@@ -12,8 +12,21 @@ The `generate` command reads `sqlcj.yaml` from the directory it is run in:
 sqlcj generate
 ```
 
-There is no configuration-path option and no configuration discovery in parent
-directories.
+`--config <path>` selects another file, so generation can run from any working
+directory:
+
+```bash
+sqlcj generate --config ../project/sqlcj.yaml
+```
+
+The option defaults to `sqlcj.yaml`, and a relative value is resolved against
+the directory the command is run in. Relative paths inside the file are still
+resolved against the directory that contains the file, not against the working
+directory. A missing or invalid explicit file reports the usual configuration
+diagnostic and exits with status `1`; there is no fallback to `sqlcj.yaml`.
+
+There is no short alias, no environment variable, and no configuration
+discovery in parent directories.
 
 ## Supported Version
 
@@ -109,8 +122,9 @@ generated/dev/example/generated/AuthorRepository.java
 ## Path Resolution
 
 A relative `schema`, `queries`, or `java.out` path is resolved against the
-directory that contains `sqlcj.yaml`, not against the process working directory
-at a later point in time. An absolute path is used as-is.
+directory that contains the configuration file, whether that file is the
+default `sqlcj.yaml` or one named by `--config`, and not against the process
+working directory at a later point in time. An absolute path is used as-is.
 
 Resolved paths are normalized lexically, so `../sql/schema.sql` is supported.
 Resolution does not require `java.out` to exist, does not expand `~`,

docs/quickstart.md

@@ -153,6 +153,7 @@ query of `sql/queries.sql`.
 
 `sqlcj generate` reads `sqlcj.yaml` from the directory it is run in, and the
 relative paths above are resolved against the directory that contains the file.
+`--config <path>` names another file when the command runs from elsewhere.
 Generated output therefore belongs in the build directory, where `mvn clean`
 removes it. See [Configuration](configuration.md) for the full file format.
 
@@ -414,8 +415,11 @@ mvn exec:java
   generate, so a query that was renamed or removed would otherwise leave a stale
   class behind that still compiles.
 - `sqlcj generate` is a separate command. It is not bound to the Maven
-  lifecycle, so it must run after `clean` and before `compile`. It must run from
-  the project root, because it reads `sqlcj.yaml` from the current directory.
+  lifecycle, so it must run after `clean` and before `compile`. The commands
+  above run from the project root, because `generate` reads `sqlcj.yaml` from
+  the current directory; from another directory, pass
+  `--config <path to sqlcj.yaml>` instead, and the paths inside the file keep
+  resolving against the project root.
 - `mvn compile` then compiles `src/main/java` together with
   `target/generated-sources/sqlcj`.