同步文档与发布说明

Author: developerworks

CHANGELOG.md

@@ -11,3 +11,10 @@ All notable changes to `rust-config-tree` are documented in this file.
   from nested schema sections are now appended instead of being skipped. This
   keeps newly added nested config sections split into their own generated files
   on regeneration.
+
+### Changed
+
+- Nested config sections are now split only when the field schema has
+  `x-tree-split = true`, for example
+  `#[schemars(extend("x-tree-split" = true))]`. Unmarked nested sections remain
+  in their parent template and parent JSON Schema.

README.de.md

@@ -29,7 +29,7 @@ Es unterstuetzt:
 - Erkennung von Include-Zyklen
 - deterministische Traversierungsreihenfolge
 - gespiegelte Sammlung von Vorlagenzielen
-- automatische YAML-Vorlagenaufteilung fuer verschachtelte Schemaabschnitte
+- Opt-in-YAML-Vorlagenaufteilung fuer mit `x-tree-split` markierte Abschnitte
 
 Anwendungen stellen ihr Schema bereit, indem sie `confique::Config` ableiten
 und `ConfigSchema` implementieren, um das Include-Feld des Schemas offenzulegen.
@@ -56,9 +56,10 @@ einen kleinen Adapter, der Includes aus der zwischengeschalteten
 use std::path::PathBuf;
 
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::ConfigSchema;
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -67,10 +68,11 @@ struct AppConfig {
     mode: String,
 
     #[config(nested)]
+    #[schemars(extend("x-tree-split" = true))]
     server: ServerConfig,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct ServerConfig {
     #[config(default = 8080)]
     port: u16,
@@ -212,7 +214,7 @@ gerendert. Das Ausgabeformat wird aus dem Ausgabepfad abgeleitet:
 - unbekannte oder fehlende Erweiterungen erzeugen YAML
 
 Verwende `write_config_schemas`, um Draft-7-JSON-Schemas fuer die
-Root-Konfiguration und verschachtelte Abschnitte zu erzeugen. Die erzeugten
+Root-Konfiguration und explizit aufgeteilte verschachtelte Abschnitte zu erzeugen. Die erzeugten
 Schemas lassen `required`-Einschraenkungen weg, damit IDEs Vervollstaendigung
 fuer partielle Konfigurationsdateien anbieten koennen, ohne fehlende Felder zu
 melden:
@@ -227,13 +229,18 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
-Bei einem Schema mit den Abschnitten `server` und `log` schreibt dies
+Mark a nested field with `#[schemars(extend("x-tree-split" = true))]` when it
+should be generated as its own `config/*.yaml` template and
+`schemas/*.schema.json` schema. Unmarked nested fields stay in the parent
+template and parent schema.
+
+Bei einem Schema mit den mit `x-tree-split` markierten Abschnitten `server` und `log` schreibt dies
 `schemas/myapp.schema.json`, `schemas/server.schema.json` und
 `schemas/log.schema.json`. Das Root-Schema enthaelt nur Felder, die in die
 Root-Konfigurationsdatei gehoeren, etwa `include` und skalare Root-Felder. Es
-laesst verschachtelte Abschnittseigenschaften bewusst weg, sodass `server` und
+laesst aufgeteilte Abschnittseigenschaften bewusst weg, sodass `server` und
 `log` nur beim Bearbeiten ihrer eigenen Abschnitts-YAML-Dateien vervollstaendigt
-werden.
+werden. Nicht markierte verschachtelte Abschnitte bleiben im Root-Schema.
 
 Verwende `write_config_templates`, um eine Root-Vorlage und jede ueber ihren
 Include-Baum erreichbare Vorlagendatei zu erzeugen:
@@ -267,7 +274,7 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 ```
 
 Root-Ziele fuer TOML/YAML binden das Root-Schema und vervollstaendigen keine
-untergeordneten Abschnittsfelder. Aufgeteilte YAML-Abschnittsziele binden ihr
+aufgeteilten untergeordneten Abschnittsfelder. Aufgeteilte YAML-Abschnittsziele binden ihr
 passendes Abschnittsschema, zum Beispiel erhaelt `config/log.yaml`
 `# yaml-language-server: $schema=../schemas/log.schema.json`. JSON- und
 JSON5-Ziele erhalten bewusst kein `$schema`-Feld; binde sie ueber
@@ -280,7 +287,7 @@ Die Vorlagenerzeugung waehlt den Quellbaum in dieser Reihenfolge:
 - der Ausgabepfad, behandelt als neuer leerer Vorlagenbaum
 
 Wenn ein Quellknoten keine Include-Liste hat, leitet `rust-config-tree`
-Kind-Vorlagendateien aus verschachtelten `confique`-Abschnitten ab. Mit dem
+Kind-Vorlagendateien aus mit `x-tree-split` markierten verschachtelten `confique`-Abschnitten ab. Mit dem
 obigen Schema erzeugt eine leere Quelle `config.example.yaml`:
 
 ```text
@@ -291,7 +298,8 @@ config/server.yaml
 Die Root-Vorlage erhaelt einen Include-Block fuer `config/server.yaml`.
 YAML-Ziele, die einem verschachtelten Abschnitt entsprechen, etwa
 `config/server.yaml`, enthalten nur diesen Abschnitt. Weitere verschachtelte
-Abschnitte werden ebenso rekursiv aufgeteilt.
+Abschnitte werden nur rekursiv aufgeteilt, wenn diese Felder ebenfalls
+`x-tree-split` tragen.
 
 Ueberschreibe `template_path_for_section`, wenn ein Abschnitt an einem anderen
 Pfad erzeugt werden soll:

README.es.md

@@ -29,7 +29,7 @@ Gestiona:
 - detección de ciclos de include
 - orden de recorrido determinista
 - recopilación reflejada de destinos de plantilla
-- división automática de plantillas YAML para secciones anidadas del esquema
+- división opt-in de plantillas YAML para secciones marcadas con `x-tree-split`
 
 Las aplicaciones proporcionan su esquema derivando `confique::Config` e
 implementando `ConfigSchema` para exponer el campo de includes del esquema.
@@ -56,9 +56,10 @@ intermedia de `confique`.
 use std::path::PathBuf;
 
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::ConfigSchema;
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -67,10 +68,11 @@ struct AppConfig {
     mode: String,
 
     #[config(nested)]
+    #[schemars(extend("x-tree-split" = true))]
     server: ServerConfig,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct ServerConfig {
     #[config(default = 8080)]
     port: u16,
@@ -214,7 +216,7 @@ recorrido de includes. El formato de salida se infiere de la ruta de salida:
 - extensiones desconocidas o ausentes generan YAML
 
 Usa `write_config_schemas` para crear JSON Schemas Draft 7 para la
-configuración raíz y las secciones anidadas. Los esquemas generados omiten
+configuración raíz y las secciones marcadas con `x-tree-split`. Los esquemas generados omiten
 restricciones `required` para que los IDE puedan ofrecer completado en archivos
 de configuración parciales sin informar campos faltantes:
 
@@ -228,11 +230,16 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
-Para un esquema con secciones `server` y `log`, esto escribe
+Mark a nested field with `#[schemars(extend("x-tree-split" = true))]` when it
+should be generated as its own `config/*.yaml` template and
+`schemas/*.schema.json` schema. Unmarked nested fields stay in the parent
+template and parent schema.
+
+Para un esquema con secciones `server` y `log` marcadas con `x-tree-split`, esto escribe
 `schemas/myapp.schema.json`, `schemas/server.schema.json` y
 `schemas/log.schema.json`. El esquema raíz contiene solo campos que pertenecen
 al archivo de configuración raíz, como `include` y campos escalares raíz. Omite
-deliberadamente las propiedades de secciones anidadas, de modo que `server` y
+deliberadamente las propiedades de secciones divididas, de modo que `server` y
 `log` solo se completan al editar sus propios archivos YAML de sección.
 
 Usa `write_config_templates` para crear una plantilla raíz y todos los archivos
@@ -279,7 +286,7 @@ La generación de plantillas elige su árbol fuente en este orden:
 - la ruta de salida, tratada como un nuevo árbol de plantillas vacío
 
 Si un nodo fuente no tiene lista de includes, `rust-config-tree` deriva
-archivos de plantilla hijos desde las secciones anidadas de `confique`. Con el
+archivos de plantilla hijos desde las secciones anidadas de `confique` marcadas con `x-tree-split`. Con el
 esquema anterior, una fuente `config.example.yaml` vacía produce:
 
 ```text
@@ -289,8 +296,8 @@ config/server.yaml
 
 La plantilla raíz recibe un bloque include para `config/server.yaml`. Los
 destinos YAML que se mapean a una sección anidada, como `config/server.yaml`,
-contienen solo esa sección. Las secciones anidadas más profundas se dividen
-recursivamente de la misma forma.
+contienen solo esa sección. Las secciones anidadas mas profundas solo se dividen
+recursivamente cuando esos campos tambien llevan `x-tree-split`.
 
 Sobrescribe `template_path_for_section` cuando una sección deba generarse en
 una ruta distinta:

README.fi.md

@@ -23,7 +23,7 @@ Se kasittelee:
 - include-syklien tunnistuksen
 - deterministisen lapikayntijarjestyksen
 - peilatun mallikohteiden keruun
-- automaattisen YAML-mallien jakamisen sisakkaisille skeemaosioille
+- opt-in YAML-mallien jakamisen `x-tree-split`-merkityille osioille
 
 Sovellukset tarjoavat skeemansa johtamalla `confique::Config`-traitin ja toteuttamalla `ConfigSchema`-traitin, joka paljastaa skeeman include-kentan.
 
@@ -47,9 +47,10 @@ Sovelluksen skeema omistaa include-kentan. `rust-config-tree` tarvitsee vain pie
 use std::path::PathBuf;
 
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::ConfigSchema;
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -58,10 +59,11 @@ struct AppConfig {
     mode: String,
 
     #[config(nested)]
+    #[schemars(extend("x-tree-split" = true))]
     server: ServerConfig,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct ServerConfig {
     #[config(default = 8080)]
     port: u16,
@@ -176,7 +178,7 @@ Mallit renderoidaan samalla skeemalla ja include-lapikaynnin saannoilla. Tuloste
 - `.json` ja `.json5` tuottavat JSON5-yhteensopivia malleja
 - tuntematon tai puuttuva paate tuottaa YAMLia
 
-Kayta `write_config_schemas`-funktiota Draft 7 JSON Schema -skeemojen luontiin juurikonfiguraatiolle ja sisakkaisille osioille. Luodut skeemat jattavat `required`-rajoitteet pois, jotta IDEt voivat tarjota taydennysta osittaisille konfiguraatiotiedostoille ilman puuttuvien kenttien virheilmoituksia:
+Kayta `write_config_schemas`-funktiota Draft 7 JSON Schema -skeemojen luontiin juurikonfiguraatiolle ja jaetuille sisakkaisille osioille. Luodut skeemat jattavat `required`-rajoitteet pois, jotta IDEt voivat tarjota taydennysta osittaisille konfiguraatiotiedostoille ilman puuttuvien kenttien virheilmoituksia:
 
 ```rust
 use rust_config_tree::write_config_schemas;
@@ -188,7 +190,12 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
-Skeemalle, jossa on `server`- ja `log`-osiot, tama kirjoittaa tiedostot `schemas/myapp.schema.json`, `schemas/server.schema.json` ja `schemas/log.schema.json`. Juuriskeema sisaltaa vain juurikonfiguraatiotiedostoon kuuluvat kentat, kuten `include` ja juuritason skalaarikentat. Se jattaa sisakkaisten osioiden ominaisuudet tarkoituksella pois, joten `server` ja `log` taydentyvat vain niiden omia osio-YAML-tiedostoja muokattaessa.
+Mark a nested field with `#[schemars(extend("x-tree-split" = true))]` when it
+should be generated as its own `config/*.yaml` template and
+`schemas/*.schema.json` schema. Unmarked nested fields stay in the parent
+template and parent schema.
+
+Skeemalle, jossa `server`- ja `log`-osiot on merkitty `x-tree-split`illa, tama kirjoittaa tiedostot `schemas/myapp.schema.json`, `schemas/server.schema.json` ja `schemas/log.schema.json`. Juuriskeema sisaltaa vain juurikonfiguraatiotiedostoon kuuluvat kentat, kuten `include` ja juuritason skalaarikentat. Se jattaa jaettujen osioiden ominaisuudet tarkoituksella pois, joten `server` ja `log` taydentyvat vain niiden omia osio-YAML-tiedostoja muokattaessa.
 
 Kayta `write_config_templates`-funktiota juurimallin ja kaikkien sen include-puusta loytyvien mallitiedostojen luontiin:
 
@@ -218,22 +225,22 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
-Juuri-TOML/YAML-kohteet sitovat juuriskeeman eivatka taydenna lapsiosioiden kenttia. Jaetut osio-YAML-kohteet sitovat vastaavan osioskeeman; esimerkiksi `config/log.yaml` saa rivin `# yaml-language-server: $schema=../schemas/log.schema.json`. JSON- ja JSON5-kohteisiin ei tarkoituksella lisata `$schema`-kenttaa; sido ne editoriasetuksilla, kuten VS Coden `json.schemas`.
+Juuri-TOML/YAML-kohteet sitovat juuriskeeman eivatka taydenna jaettujen lapsiosioiden kenttia. Jaetut osio-YAML-kohteet sitovat vastaavan osioskeeman; esimerkiksi `config/log.yaml` saa rivin `# yaml-language-server: $schema=../schemas/log.schema.json`. JSON- ja JSON5-kohteisiin ei tarkoituksella lisata `$schema`-kenttaa; sido ne editoriasetuksilla, kuten VS Coden `json.schemas`.
 
 Mallien luonti valitsee lahdepuun tassa jarjestyksessa:
 
 - olemassa oleva konfiguraatiopolku
 - olemassa oleva tulostemallipolku
 - tulostepolku, jota kasitellaan uutena tyhjana mallipuuna
 
-Jos lahdesolmulla ei ole include-listaa, `rust-config-tree` johtaa lapsimallitiedostot sisakkaisista `confique`-osioista. Ylla olevalla skeemalla tyhja `config.example.yaml`-lahde tuottaa:
+Jos lahdesolmulla ei ole include-listaa, `rust-config-tree` johtaa lapsimallitiedostot `x-tree-split`-merkityista sisakkaisista `confique`-osioista. Ylla olevalla skeemalla tyhja `config.example.yaml`-lahde tuottaa:
 
 ```text
 config.example.yaml
 config/server.yaml
 ```
 
-Juurimalli saa include-lohkon tiedostolle `config/server.yaml`. YAML-kohteet, jotka vastaavat sisakkaista osiota, kuten `config/server.yaml`, sisaltavat vain kyseisen osion. Syvemmat sisakkaiset osiot jaetaan rekursiivisesti samalla tavalla.
+Juurimalli saa include-lohkon tiedostolle `config/server.yaml`. YAML-kohteet, jotka vastaavat sisakkaista osiota, kuten `config/server.yaml`, sisaltavat vain kyseisen osion. Syvemmat sisakkaiset osiot jaetaan rekursiivisesti vain, kun myos niilla kentilla on `x-tree-split`.
 
 Ohita `template_path_for_section`, kun osio tulee luoda eri polkuun:
 

README.fr.md

@@ -31,8 +31,8 @@ Il gere :
 - la detection des cycles d'inclusion ;
 - un ordre de traversee deterministe ;
 - la collecte miroir des cibles de modeles ;
-- le decoupage automatique des modeles YAML pour les sections de schema
-  imbriquees.
+- decoupage opt-in des modeles YAML pour les sections imbriquees
+  marquees `x-tree-split`.
 
 Les applications fournissent leur schema en derivant `confique::Config` et en
 implementant `ConfigSchema` pour exposer le champ d'inclusion du schema.
@@ -59,9 +59,10 @@ intermediaire `confique`.
 use std::path::PathBuf;
 
 use confique::Config;
+use schemars::JsonSchema;
 use rust_config_tree::ConfigSchema;
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct AppConfig {
     #[config(default = [])]
     include: Vec<PathBuf>,
@@ -70,10 +71,11 @@ struct AppConfig {
     mode: String,
 
     #[config(nested)]
+    #[schemars(extend("x-tree-split" = true))]
     server: ServerConfig,
 }
 
-#[derive(Debug, Config)]
+#[derive(Debug, Config, JsonSchema)]
 struct ServerConfig {
     #[config(default = 8080)]
     port: u16,
@@ -217,7 +219,7 @@ d'inclusions. Le format de sortie est deduit du chemin de sortie :
 - les extensions inconnues ou absentes generent du YAML.
 
 Utilisez `write_config_schemas` pour creer des schemas JSON Draft 7 pour la
-configuration racine et les sections imbriquees. Les schemas generes omettent
+configuration racine et les sections imbriquees decoupees. Les schemas generes omettent
 les contraintes `required` afin que les IDE puissent proposer la completion pour
 des fichiers de configuration partiels sans signaler de champs manquants :
 
@@ -231,13 +233,18 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 }
 ```
 
-Pour un schema avec les sections `server` et `log`, cela ecrit
+Mark a nested field with `#[schemars(extend("x-tree-split" = true))]` when it
+should be generated as its own `config/*.yaml` template and
+`schemas/*.schema.json` schema. Unmarked nested fields stay in the parent
+template and parent schema.
+
+Pour un schema avec les sections `server` et `log` marquees `x-tree-split`, cela ecrit
 `schemas/myapp.schema.json`, `schemas/server.schema.json` et
 `schemas/log.schema.json`. Le schema racine ne contient que les champs qui
 appartiennent au fichier racine, comme `include` et les champs scalaires racine.
-Il omet intentionnellement les proprietes des sections imbriquees, donc `server`
+Il omet intentionnellement les proprietes des sections decoupees, donc `server`
 et `log` ne sont completes que lors de l'edition de leurs propres fichiers YAML
-de section.
+de section. Les sections imbriquees non marquees restent dans le schema racine.
 
 Utilisez `write_config_templates` pour creer un modele racine et chaque fichier
 modele accessible depuis son arbre d'inclusion :
@@ -283,7 +290,7 @@ La generation de modeles choisit son arbre source dans cet ordre :
 - le chemin de sortie, traite comme un nouvel arbre de modeles vide.
 
 Si un noeud source n'a pas de liste d'inclusions, `rust-config-tree` derive les
-fichiers modeles enfants depuis les sections `confique` imbriquees. Avec le
+fichiers modeles enfants depuis les sections `confique` imbriquees marquees `x-tree-split`. Avec le
 schema ci-dessus, une source `config.example.yaml` vide produit :
 
 ```text
@@ -294,7 +301,7 @@ config/server.yaml
 Le modele racine recoit un bloc d'inclusion pour `config/server.yaml`. Les
 cibles YAML qui correspondent a une section imbriquee, comme
 `config/server.yaml`, ne contiennent que cette section. Les sections encore plus
-imbriquees sont separees recursivement de la meme facon.
+imbriquees ne sont separees recursivement que lorsque ces champs portent aussi `x-tree-split`.
 
 Remplacez `template_path_for_section` lorsqu'une section doit etre generee a un
 autre chemin :
@@ -415,7 +422,7 @@ d'execution. Cela ecrit aussi le schema racine et les schemas de section au
 chemin de schema choisi.
 
 `config-schema --output <path>` ecrit le schema JSON Draft 7 racine et les
-schemas de section. Si aucun chemin de sortie n'est fourni, le schema racine est
+schemas de section. Les sections imbriquees non marquees restent dans le schema racine. Si aucun chemin de sortie n'est fourni, le schema racine est
 ecrit dans `schemas/config.schema.json`.
 
 `config-validate` charge l'arbre complet de configuration d'execution et lance