Add a page about how the configuration is computed (#2446)

Co-authored-by: Jules Aguillon <[email protected]>

Author: gpetiot

doc/configuration.mld

@@ -0,0 +1,50 @@
+{0 How OCamlFormat computes its configuration}
+
+{1 Configuration files}
+
+Ocamlformat fetches the following files on the file system:
+
+1. [.git], [.hg] or [dune-project]
+2. [.ocamlformat] and [.ocp-indent]
+3. [.ocamlformat-ignore] and [.ocamlformat-enable]
+
+(1.) files are used to determine the {b project root}, which can be overriden by the [--root] option, they are looked up from the path of the file to format, and upwards following parent directories, until the first one is found.
+
+(2.) and (3.) are looked up from the path of the file to format, and following up the parents up to the project root.
+
+(2.) are the {b configuration files}, they contain the options used to configure ocamlformat. A global [.ocamlformat] file can also be used: [$XDG_CONFIG_HOME/ocamlformat] (if defined).
+
+
+{1 How the configuration is built}
+
+The configuration files are considered in sequence, starting from the root of the project, and down to the directory of the file to format, overriding one or many options at each application.
+
++ The initial configuration is equal to the [default] (or [conventional]) profile.
++ The options passed through the configuration files are applied.
++ The options passed through the [OCAMLFORMAT] environment variable are applied, overriding one or many options at a time.
++ The options passed through the command line are applied, overriding one or many options at a time.
+
+When the option [--enable-outside-detected-project] is set, [.ocamlformat] files outside of the project are read, if no [.ocamlformat] file has been found then then apply the global configuration [$XDG_CONFIG_HOME/ocamlformat] (if defined). The global configuration file is ignore in any other case.
+
+When this option is not set, [.ocamlformat] files outside of the project are ignored.
+
+If no configuration file is found, the formatting is disabled.
+
+{1 Overriding the configuration in the source}
+
+Note that some options can be overriden directly in the source, with attributes like:
+
+{@ocaml[
+(* attributes attached to algebraic constructs *)
+x [@ocamlformat "option=value,option=value"];;
+
+(* item attributes, attached to "blocks" *)
+y [@@ocamlformat "option=value,option=value"];;
+
+(* floating attributes, standalone *)
+[@@@ocamlformat "option=value,option=value"]
+]}
+
+All "formatting options" (listed in the {{!page-manpage_ocamlformat}manpage}) can be set in attributes.
+
+Among the non-formatting options only [enable]/[disable] can be set in floatting attributes.

doc/editor_setup.mld

@@ -3,6 +3,7 @@
 {1 Enable formatting outside project}
 
 OCamlFormat detects your current project if there is a [.git], a [.hg] or a [dune-project] file in one of the ancestry directories.
+For more details, read about {{!page-configuration}how OCamlFormat finds its root project and computes its configuration}.
 
 By default, when the option [--enable-outside-detected-project] is not set, [.ocamlformat] files outside of the current project (including the one in [XDG_CONFIG_HOME]) are not read. If no configuration file is found, then the formatting is disabled.
 

doc/getting_started.mld

@@ -72,12 +72,7 @@ Options can be modified by the means of:
 - a global [[@@@ocamlformat "option=VAL"]] attribute in the processed file
 - an [[@@ocamlformat "option=VAL"]] attribute on an expression in the processed file
 
-[.ocamlformat] files in the containing and all ancestor directories for each input file are used, as well as the global [.ocamlformat] file defined in [$XDG_CONFIG_HOME/ocamlformat]. The global [.ocamlformat] file has the lowest priority, then the closer the directory is to the processed file, the higher the priority.
-
-When the option [--enable-outside-detected-project] is set, [.ocamlformat] files outside of the project (including the one in [XDG_CONFIG_HOME]) are read. The project root of an input file is taken to be the nearest ancestor directory that contains a [.git] or [.hg] or [dune-project] file.
-When this option is not set, [.ocamlformat] files outside of the project are ignored. If no configuration file is found, formatting is disabled.
-
-An [.ocamlformat-ignore] file specifies files that OCamlFormat should ignore. Each line in an [.ocamlformat-ignore] file specifies a filename relative to the directory containing the [.ocamlformat-ignore] file. Lines starting with [#] are ignored and can be used as comments.
+For more details, read about {{!page-configuration}how OCamlFormat finds its root project and computes its configuration}.
 
 {1 Version}
 

doc/index.mld

@@ -9,6 +9,7 @@ OCamlFormat is a tool to format OCaml code.
 
 {1 Table of Content}
 - {{!page-getting_started}Getting started}
+- {{!page-configuration}How OCamlFormat computes its configuration}
 - {{!page-editor_setup}Editor setup}
 - {{!page-manpage_ocamlformat}Manpage}
 - {{!page-howtos}How-To's}