nixos/doc: add documentation for formats.hocon

nixos/doc/manual/development/settings-options.section.md

@@ -46,6 +46,159 @@ have a predefined type and string generator already declared under
  `generate` to build a Java `.properties` file, taking
  care of the correct escaping, etc.
 
+`pkgs.formats.hocon` { *`generator`* ? `<derivation>`, *`validator`* ? `<derivation>`, *`doCheck`* ? true }
+
+: A function taking an attribute set with values
+
+ `generator`
+
+ : A derivation used for converting the JSON output
+  from the nix settings into HOCON. This might be
+  useful if your HOCON variant is slightly different
+  from the java-based one, or for testing purposes.
+
+ `validator`
+
+ : A derivation used for verifying that the HOCON
+  output is correct and parsable. This might be
+  useful if your HOCON variant is slightly different
+  from the java-based one, or for testing purposes.
+
+ `doCheck`
+
+ : Whether to enable/disable the validator check.
+
+ It returns an attrset with a `type`, `generate` function,
+ and a `lib` attset, as specified [below](#pkgs-formats-result).
+ Some of the lib functions will be best understood if you have
+ read the reference specification. You can find this
+ specification here:
+
+ <https://github.com/lightbend/config/blob/main/HOCON.md>
+
+ Inside of `lib`, you will find these functions
+
+ `mkInclude`
+
+ : This is used together with a specially named
+  attribute `includes`, to include other HOCON
+  sources into the document.
+
+  The function has a shorthand variant where it
+  is up to the HOCON parser to figure out what type
+  of include is being used. The include will default
+  to being non-required. If you want to be more
+  explicit about the details of the include, you can
+  provide an attrset with following arguments
+
+  `required`
+
+  : Whether the parser should fail upon failure
+  to include the document
+
+  `type`
+
+  : Type of the source of the included document.
+  Valid values are `file`, `url` and `classpath`.
+  See upstream documentation for the semantics
+  behind each value
+
+  `value`
+
+  : The URI/path/classpath pointing to the source of
+  the document to be included.
+
+  `Example usage:`
+
+  ```nix
+  let
+  format = pkgs.formats.hocon { };
+  hocon_file = pkgs.writeText "to_include.hocon" ''
+  a = 1;
+  '';
+  in {
+  some.nested.hocon.attrset = {
+  _includes = [
+  (format.lib.mkInclude hocon_file)
+  (format.lib.mkInclude "https://example.com/to_include.hocon")
+  (format.lib.mkInclude {
+  required = true;
+  type = "file";
+  value = include_file;
+  })
+  ];
+  ...
+  };
+  }
+  ```
+
+ `mkAppend`
+
+ : This is used to invoke the `+=` operator.
+  This can be useful if you need to add something
+  to a list that is included from outside of nix.
+  See upstream documentation for the semantics
+  behind the `+=` operation.
+
+  `Example usage:`
+
+  ```nix
+  let
+  format = pkgs.formats.hocon { };
+  hocon_file = pkgs.writeText "to_include.hocon" ''
+  a = [ 1 ];
+  b = [ 2 ];
+  '';
+  in {
+  _includes = [
+  (format.lib.mkInclude hocon_file)
+  ];
+
+  c = 3;
+  a = format.lib.mkAppend 3;
+  b = format.lib.mkAppend (format.lib.mkSubstitution "c");
+  }
+  ```
+
+ `mkSubstitution`
+
+ : This is used to make HOCON substitutions.
+  Similarly to `mkInclude`, this function has
+  a shorthand variant where you just give it
+  the string with the substitution value.
+  The substitution is not optional by default.
+  Alternatively, you can provide an attrset
+  with more options
+
+  `optional`
+
+  : Whether the parser should fail upon
+  failure to fetch the substitution value.
+
+  `value`
+
+  : The name of the variable to use for
+  substitution.
+
+  See upstream documentation for semantics
+  behind the substitution functionality.
+
+  `Example usage:`
+
+  ```nix
+  let
+  format = pkgs.formats.hocon { };
+  in {
+  a = 1;
+  b = format.lib.mkSubstitution "a";
+  c = format.lib.mkSubstition "SOME_ENVVAR";
+  d = format.lib.mkSubstition {
+  value = "SOME_OPTIONAL_ENVVAR";
+  optional = true;
+  };
+  }
+  ```
+
 `pkgs.formats.json` { }
 
 : A function taking an empty attribute set (for future extensibility)