Add configuration doc

core/src/main/java/io/jstach/rainbowgum/Defaults.java

@@ -51,6 +51,8 @@ public class Defaults {
 
 	static final Property<URI> fileProperty = Property.builder().map(URI::new).build(LogProperties.FILE_PROPERTY);
 
+	static final Property<URI> outputProperty = Property.builder().map(URI::new).build(LogProperties.OUTPUT_PROPERTY);
+
 	Defaults(LogProperties logProperties) {
 		this.properties = logProperties;
 	}

core/src/main/java/io/jstach/rainbowgum/LogConfig.java

@@ -61,7 +61,7 @@ default LogOutputProvider outputProvider() {
 	 * @throws IOException if output fails fast
 	 */
 	default LogOutput output(URI uri) throws IOException {
-		return outputProvider().of(uri);
+		return outputProvider().output(uri);
 	}
 
 	/**

core/src/main/java/io/jstach/rainbowgum/LogOutputProvider.java

@@ -18,7 +18,7 @@ public interface LogOutputProvider extends AutoCloseable {
 	 * @return output.
 	 * @throws IOException if unable to use the URI.
 	 */
-	LogOutput of(URI uri) throws IOException;
+	LogOutput output(URI uri) throws IOException;
 
 	default void close() {
 	}
@@ -38,7 +38,7 @@ enum DefaultOutputProvider implements LogOutputProvider {
 	INSTANCE;
 
 	@Override
-	public LogOutput of(URI uri) throws IOException {
+	public LogOutput output(URI uri) throws IOException {
 		String scheme = uri.getScheme();
 		String path = uri.getPath();
 		if (scheme == null && path != null) {

core/src/main/java/io/jstach/rainbowgum/LogProperties.java

@@ -1,5 +1,6 @@
 package io.jstach.rainbowgum;
 
+import java.lang.System.Logger.Level;
 import java.util.Arrays;
 import java.util.Comparator;
 import java.util.List;
@@ -19,6 +20,41 @@
 /**
  * Provides String based properties like {@link System#getProperty(String)} for default
  * configuration of logging levels and output.
+ * <p>
+ * If a custom {@link LogProperties} is configured the default implementation uses System
+ * properties.
+ * <p>
+ * The builtin propertiers to configure RainbowGum are modeled after <a href=
+ * "https://docs.spring.io/spring-boot/docs/3.1.0/reference/html/features.html#features.logging">
+ * Spring Boot logging </a>
+ * 
+ * <table class="table">
+ * <caption>Builtin Properties</caption>
+ * <tr>
+ * <th>Property Pattern</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>{@value #LEVEL_PREFIX} + {@value #SEP} + logger = LEVEL</td>
+ * <td>Sets the level for the logger. If logger name is missing then it is considered the
+ * root logger. {@link Level#INFO} is the default level for the root logger.</td>
+ * </tr>
+ * <tr>
+ * <td>{@value #CHANGE_PREFIX} + {@value #SEP} + logger = boolean</td>
+ * <td>Allows runtime changing of levels for the logger. By design RainbowGum does not
+ * allow loggers to change levels once initialized. This configuration will allow the
+ * level to be changed for the logger and its children and by default is false as the
+ * builtin {@link LogProperties} is generally static (system properties).</td>
+ * </tr>
+ * <tr>
+ * <td>{@value #FILE_PROPERTY} = URI</td>
+ * <td>A URI or file path to log to a file.</td>
+ * </tr>
+ * <tr>
+ * <td>{@value #OUTPUT_PROPERTY} = URI</td>
+ * <td>A URI to an {@linkplain LogOutput output}.</td>
+ * </tr>
+ * </table>
  */
 @FunctionalInterface
 public interface LogProperties {
@@ -34,7 +70,8 @@ public interface LogProperties {
 	static final String ROOT_PREFIX = "logging" + SEP;
 
 	/**
-	 * Logging level properties prefix.
+	 * Logging level properties prefix. The value should be the name of a
+	 * {@linkplain java.lang.System.Logger.Level level}.
 	 */
 	static final String LEVEL_PREFIX = ROOT_PREFIX + "level";
 
@@ -44,9 +81,14 @@ public interface LogProperties {
 	static final String CHANGE_PREFIX = ROOT_PREFIX + "change";
 
 	/**
-	 * Logging file property for default single file appending.
+	 * Logging file property for default single file appending. The value should be a URI.
 	 */
-	static final String FILE_PROPERTY = ROOT_PREFIX + "file";
+	static final String FILE_PROPERTY = ROOT_PREFIX + "file.name";
+
+	/**
+	 * Logging output property for appending to a resource. The value should be a URI.
+	 */
+	static final String OUTPUT_PROPERTY = ROOT_PREFIX + "output";
 
 	/**
 	 * Analogous to {@link System#getProperty(String)}.

core/src/main/java/io/jstach/rainbowgum/LogRouter.java

@@ -238,9 +238,15 @@ Router build() {
 				List<AppenderProvider> appenders = new ArrayList<>(this.appenders);
 				if (appenders.isEmpty()) {
 					appenders.add(LogAppender.builder().output(LogOutput.ofStandardOut()).build());
-					config.properties()
-						.property(Defaults.fileProperty) //
-						.map(u -> config.outputProvider().of(u))
+					config.get(Defaults.fileProperty) //
+						.map(config::output) //
+						.map(o -> {
+							return LogAppender.builder().output(o).build();
+						}) //
+						.optional() //
+						.ifPresent(appenders::add);
+					config.get(Defaults.outputProperty) //
+						.map(config::output) //
 						.map(o -> {
 							return LogAppender.builder().output(o).build();
 						}) //

doc/overview.html

@@ -159,6 +159,17 @@ <h3 id="3.2">Gradle</h3>
 
 <h2 id="configuration">Configuration</h2>
 
+Most configuration of Rainbow Gum is done by adding extension jars as runtime dependencies
+or by setting key values in {@linkplain io.jstach.rainbowgum.LogProperties properties}.
+
+By default Rainbow Gum uses System properties for properties but a configuration system
+can be used instead.
+
+Logger levels and output can be configured through properties.
+
+More information on builtin properties is in  {@link io.jstach.rainbowgum.LogProperties}.
+
+IF you would like use your own properties system see {@link io.jstach.rainbowgum.spi.RainbowGumServiceProvider}.
 
 <h2 id="integration">Extensions and Integrations</h2>
 

todo.md

@@ -24,10 +24,10 @@ logical resource (it might not be a single physical resource particularly in the
 
 ## TODO before release
 
-[ ] A network based LogOutput. Probably AMQP.
-[ ] A console theme.
-[ ] Remove all the field based formatters.
-[ ] Code samples and instructions for custom configuration.
-[ ] Scoped Value plugin
-[ ] JEP 430 String templates example
-
+- [ ] A network based LogOutput. Probably AMQP.
+- [ ] A console theme.
+- [ ] Remove all the field based formatters.
+- [ ] Code samples and instructions for custom configuration.
+- [ ] Scoped Value plugin
+- [ ] JEP 430 String templates example
+