Added documentation regarding the environment_settings option in the project.yml file (Issue #7654, PR #9392)

# Description

Add documentation regarding the `environment_settings` option in `project.yml`.

Part of #7654

# Self Check:

- [x] Attached issue to pull request
- [x] Changelog entry
- [x] Type annotations are present
- [x] Code is clear and sufficiently documented
- [x] No (preventable) type errors (check using make mypy or make mypy-diff)
- [x] Sufficient test cases (reproduces the bug/tests the requested feature)
- [x] Correct, in line with design
- [x] End user documentation is included or an issue is created for end-user documentation
- [ ] ~~If this PR fixes a race condition in the test suite, also push the fix to the relevant stable branche(s) (see [test-fixes](https://internal.inmanta.com/development/core/tasks/build-master.html#test-fixes) for more info)~~

Author: arnaudsjs

changelogs/unreleased/add-documentation-environement-settings.yml

@@ -0,0 +1,6 @@
+---
+description: "Added documentation regarding the `environment_settings` option in the project.yml file"
+issue-nr: 7654
+issue-repo: inmanta-core
+change-type: patch
+destination-branches: [master, iso8]

docs/reference/projectyml.rst

@@ -54,6 +54,9 @@ The code snippet below provides an example of a complete ``project.yml`` file:
         extra-index-url: []
         pre: false
         use-system-config: false
+    environment_settings:
+        auto_deploy: true
+        server_compile: true
 
 
 .. _specify_location_pip:
@@ -93,7 +96,7 @@ Setting this to ``true`` will have the following consequences:
   environment variables or pip config files, and passed to pip as extra indexes.
 
 - If ``pre`` is set, it will supersede pip's ``pre`` option set by the ``PIP_PRE`` environment variable or in pip
-config file. When true, pre-release versions are allowed when installing v2 modules or v1 modules' dependencies.
+  config file. When true, pre-release versions are allowed when installing v2 modules or v1 modules' dependencies.
 
 - :term:`Executors<executor>` live on the same host as the server, and so they will share the pip config at the system level.
 
@@ -214,6 +217,18 @@ Changes relative to ``inmanta-2023.4`` (OSS):
     - Pip environment variables are no longer ignored when ``pip.use-system-config`` is true and the corresponding option
       from the ``project_yml`` is unset.
 
+Environment settings
+--------------------
+
+This section explains the behavior of the ``environment_settings`` configuration option in the ``project.yml`` file. This
+option allows a project to indicate that it needs certain environment settings to be set to a specific value. These environment
+settings are applied on the server each time the ``inmanta export`` command is executed. All environment settings exported like
+this will become protected. This means that it will no longer be possible to update these settings using the API endpoints to
+update environment settings or via the web-console. In other words, these environment settings are from then on managed using the
+project.yml file only. To unprotect an environment setting, remove it from the project.yml file again and run the
+``inmanta export`` command.
+
+
 Module metadata files
 #####################
 

src/inmanta/module.py

@@ -1511,8 +1511,9 @@ class ProjectMetadata(Metadata, MetadataFieldRequires):
     :param pip: A configuration section that holds information about the pip configuration that should be taken into account
                 when installing Python packages (See: :py:class:`inmanta.module.ProjectPipConfig` for more details).
     :param environment_settings: The environment settings that need to be configured on the server for this project.
-                                 The environment settings can be updated on export by setting the
-                                 `--update-environment-settings` option on the `inmanta export` command.
+                                 The settings will be applied on the server when the `inmanta export` command is run.
+                                 Environment settings specified here cannot be updated via the regular API endpoints
+                                 to update environment settings as long as they are in this list.
     """
 
     _raw_parser: typing.ClassVar[type[YamlParser]] = YamlParser