clarify docs for default_prefix and friends (#750)

* clarify docs for `default_prefix` and friends * add news * pre-commit
conda · Feb 6, 2024 · dd3c9bc · dd3c9bc
1 parent b74b31f
commit dd3c9bc
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 15 deletions.
diff --git a/CONSTRUCT.md b/CONSTRUCT.md
@@ -500,20 +500,22 @@ _required:_ no<br/>
 _type:_ string<br/>
 
 Set default install prefix. On Linux, if not provided, the default prefix
-is `${HOME}/${NAME}` (or, if `HOME` is not set, `/opt/${NAME}`). On Windows,
+is `${HOME}/<NAME>` (or, if `HOME` is not set, `/opt/<NAME>`). On Windows,
 this is used only for "Just Me" installation; for "All Users" installation,
 use the `default_prefix_all_users` key. If not provided, the default prefix
-is `${USERPROFILE}\${NAME}`.
+is `%USERPROFILE%\<NAME>`. Environment variables will be expanded at
+installation time.
 
 ### `default_prefix_domain_user`
 
 _required:_ no<br/>
 _type:_ string<br/>
 
 Set default installation prefix for domain user. If not provided, the
-installation prefix for domain user will be `${LOCALAPPDATA}\${NAME}`.
+installation prefix for domain user will be `%LOCALAPPDATA%\<NAME>`.
 By default, it is different from the `default_prefix` value to avoid installing
-the distribution in the roaming profile. Windows only.
+the distribution in the roaming profile. Environment variables will be expanded
+at installation time. Windows only.
 
 ### `default_prefix_all_users`
 
@@ -522,7 +524,8 @@ _type:_ string<br/>
 
 Set default installation prefix for All Users installation. If not provided,
 the installation prefix for all users installation will be
-`${ALLUSERSPROFILE}\${NAME}`. Windows only.
+`%ALLUSERSPROFILE%\<NAME>`. Environment variables will be expanded at installation
+time. Windows only.
 
 ### `default_location_pkg`
 

diff --git a/constructor/construct.py b/constructor/construct.py
@@ -366,23 +366,26 @@
 
     ('default_prefix',         False, str, r'''
 Set default install prefix. On Linux, if not provided, the default prefix
-is `${HOME}/${NAME}` (or, if `HOME` is not set, `/opt/${NAME}`). On Windows,
+is `${HOME}/<NAME>` (or, if `HOME` is not set, `/opt/<NAME>`). On Windows,
 this is used only for "Just Me" installation; for "All Users" installation,
 use the `default_prefix_all_users` key. If not provided, the default prefix
-is `${USERPROFILE}\${NAME}`.
+is `%USERPROFILE%\<NAME>`. Environment variables will be expanded at
+installation time.
 '''),  # noqa
 
     ('default_prefix_domain_user', False, str, r'''
 Set default installation prefix for domain user. If not provided, the
-installation prefix for domain user will be `${LOCALAPPDATA}\${NAME}`.
+installation prefix for domain user will be `%LOCALAPPDATA%\<NAME>`.
 By default, it is different from the `default_prefix` value to avoid installing
-the distribution in the roaming profile. Windows only.
+the distribution in the roaming profile. Environment variables will be expanded
+at installation time. Windows only.
 '''),  # noqa
 
     ('default_prefix_all_users', False, str, r'''
 Set default installation prefix for All Users installation. If not provided,
 the installation prefix for all users installation will be
-`${ALLUSERSPROFILE}\${NAME}`. Windows only.
+`%ALLUSERSPROFILE%\<NAME>`. Environment variables will be expanded at installation
+time. Windows only.
 '''),  # noqa
 
     ('default_location_pkg', False, str, '''

diff --git a/docs/source/construct-yaml.md b/docs/source/construct-yaml.md
@@ -500,20 +500,22 @@ _required:_ no<br/>
 _type:_ string<br/>
 
 Set default install prefix. On Linux, if not provided, the default prefix
-is `${HOME}/${NAME}` (or, if `HOME` is not set, `/opt/${NAME}`). On Windows,
+is `${HOME}/<NAME>` (or, if `HOME` is not set, `/opt/<NAME>`). On Windows,
 this is used only for "Just Me" installation; for "All Users" installation,
 use the `default_prefix_all_users` key. If not provided, the default prefix
-is `${USERPROFILE}\${NAME}`.
+is `%USERPROFILE%\<NAME>`. Environment variables will be expanded at
+installation time.
 
 ### `default_prefix_domain_user`
 
 _required:_ no<br/>
 _type:_ string<br/>
 
 Set default installation prefix for domain user. If not provided, the
-installation prefix for domain user will be `${LOCALAPPDATA}\${NAME}`.
+installation prefix for domain user will be `%LOCALAPPDATA%\<NAME>`.
 By default, it is different from the `default_prefix` value to avoid installing
-the distribution in the roaming profile. Windows only.
+the distribution in the roaming profile. Environment variables will be expanded
+at installation time. Windows only.
 
 ### `default_prefix_all_users`
 
@@ -522,7 +524,8 @@ _type:_ string<br/>
 
 Set default installation prefix for All Users installation. If not provided,
 the installation prefix for all users installation will be
-`${ALLUSERSPROFILE}\${NAME}`. Windows only.
+`%ALLUSERSPROFILE%\<NAME>`. Environment variables will be expanded at installation
+time. Windows only.
 
 ### `default_location_pkg`
 

diff --git a/news/750-default-prefix-docs b/news/750-default-prefix-docs
@@ -0,0 +1,19 @@
+### Enhancements
+
+* <news item>
+
+### Bug fixes
+
+* <news item>
+
+### Deprecations
+
+* <news item>
+
+### Docs
+
+* Clarify environment variables role in `default_prefix` and friends on Windows. (#748 via #750)
+
+### Other
+
+* <news item>