Make key in TOML env file consistent (#43)

Some keys in the config are named as `..._path` and some as `..._dir`.
This is not good to remember that ("was it path or dir at the end?").

This commit changes that and makes all consistent. We have now the latter
name with `..._dir`.

Author: tomschr

changelog.d/43.bugfix.rst

@@ -0,0 +1 @@
+Make keys in TOML env file consistent

etc/docbuild/env.example.toml

@@ -29,28 +29,35 @@ canonical_url_domain = "https://docs.example.com"
 [paths]
 # Section "paths": Defines several paths
 # Paths can hold placeholders in brackets.
-config_dir = "/etc/docbuild"
+root_config_dir = "/etc/docbuild"
+jinja_dir = "{root_config_dir}/jinja-doc-suse-com"
+config_dir = "{root_config_dir}/config.d"
+server_rootfiles_dir = "{root_config_dir}/server-root-files-doc-suse-com"
+#
+base_cache_dir = "/var/cache/docserv"
+base_server_cache_dir = "{base_cache_dir}/{server.name}"
+base_tmp_dir = "/var/tmp/docbuild"
 repo_dir = "/data/docserv/repos/permanent-full/"
 temp_repo_dir = "/data/docserv/repos/temporary-branches/"
-base_cache_dir = "/var/cache/docserv"
-cache_dir = "{base_cache_dir}/{server.name}"
-meta_cache_dir = "{base_cache_dir}/meta"
+# cache_dir = "{base_cache_dir}/{server.name}"
+meta_cache_dir = "{base_cache_dir}/{server.name}/meta"
 
 [paths.tmp]
 # Section "paths.tmp": Definies temporary paths
 # Paths can hold placeholders in brackets.
-tmp_base_path = "/tmp/docbuild"
-tmp_path = "{tmp_base_path}/doc-example-com"
-tmp_deliverable_path = "{paths.tmp.tmp_path}/deliverable/"
-tmp_build_dir = "{tmp_path}/build/{{product}}-{{docset}}-{{lang}}"
-tmp_out_path = "{tmp_path}/out/"
-log_path = "{tmp_path}/log/"
+tmp_base_dir = "{paths.base_tmp_dir}"
+tmp_dir = "{tmp_base_dir}/doc-example-com"
+tmp_metadata_dir = "{tmp_dir}/metadata"
+tmp_deliverable_dir = "{paths.tmp.tmp_dir}/deliverable/"
+tmp_build_dir = "{tmp_dir}/build/{{product}}-{{docset}}-{{lang}}"
+tmp_out_dir = "{tmp_dir}/out/"
+log_dir = "{tmp_dir}/log/"
 tmp_deliverable_name = "{{product}}_{{docset}}_{{lang}}_XXXXXX"
 
 [paths.target]
 # Section "paths.target": Definies target paths
-target_path = "[email protected]:/srv/docs"
-backup_path = "/data/docbuild/external-builds/"
+target_dir = "[email protected]:/srv/docs"
+backup_dir = "/data/docbuild/external-builds/"
 
 
 [build]

src/docbuild/cli/defaults.py

@@ -18,8 +18,8 @@
         'temp_repo_dir': '/data/docserv/repos/temporary-branches/',
     },
     'paths.tmp': {
-        'tmp_base_path': '/tmp',
-        'tmp_path': '{tmp_base_path}/doc-example-com',
+        'tmp_base_dir': '/tmp',
+        'tmp_dir': '{tmp_base_dir}/doc-example-com',
     },
 }
 """Default configuration for the application."""
@@ -32,8 +32,8 @@
         'temp_repo_dir': '/data/docserv/repos/temporary-branches/',
     },
     'paths.tmp': {
-        'tmp_base_path': f'/var/tmp/{APP_NAME}',
-        'tmp_path': '{tmp_base_path}/doc-example-com',
+        'tmp_base_dir': f'/var/tmp/{APP_NAME}',
+        'tmp_dir': '{tmp_base_dir}/doc-example-com',
     },
 }
 """Default configuration for the environment."""

tests/cli/config/sample-env.toml

@@ -39,18 +39,18 @@ meta_cache_dir = "{base_cache_dir}/meta"
 [paths.tmp]
 # Section "paths.tmp": Definies temporary paths
 # Paths can hold placeholders in brackets.
-tmp_base_path = "/tmp/docbuild"
-tmp_path = "{tmp_base_path}/doc-example-com"
-tmp_deliverable_path = "{paths.tmp.tmp_path}/deliverable/"
-tmp_build_dir = "{tmp_path}/build/{{product}}-{{docset}}-{{lang}}"
-tmp_out_path = "{tmp_path}/out/"
-log_path = "{tmp_path}/log/"
+tmp_base_dir = "/tmp/docbuild"
+tmp_dir = "{tmp_base_dir}/doc-example-com"
+tmp_deliverable_dir = "{paths.tmp.tmp_dir}/deliverable/"
+tmp_build_dir = "{tmp_dir}/build/{{product}}-{{docset}}-{{lang}}"
+tmp_out_dir = "{tmp_dir}/out/"
+log_path = "{tmp_dir}/log/"
 tmp_deliverable_name = "{{product}}_{{docset}}_{{lang}}_XXXXXX"
 
 [paths.target]
 # Section "paths.target": Definies target paths
-target_path = "[email protected]:/srv/docs"
-backup_path = "/data/docbuild/external-builds/"
+target_dir = "[email protected]:/srv/docs"
+backup_dir = "/data/docbuild/external-builds/"
 
 
 [build]

tests/cli/config/test_environment.py

@@ -67,8 +67,8 @@ def test_showconfig_env_role_option(
             'repo_dir': '/data/docserv/repos/permanent-full/',
             'temp_repo_dir': '/data/docserv/repos/temporary-branches/',
             'tmp': {
-                'tmp_base_path': '/tmp',
-                'tmp_path': '/tmp/doc-example-com',
+                'tmp_base_dir': '/tmp',
+                'tmp_dir': '/tmp/doc-example-com',
             },
         },
     }

tests/config/app/test_app_replace_placeholders.py

@@ -1,3 +1,4 @@
+from typing import Any
 import re
 
 import pytest
@@ -15,27 +16,27 @@ def test_replace_placeholders():
         'server': {'name': 'example.com', 'url': 'https://{server.name}'},
         'paths': {
             'config_dir': '/etc/myapp',
-            'tmp': {'tmp_base_path': '/tmp/myapp'},
-            'full_tmp_path': '{paths.tmp.tmp_base_path}/session',
+            'tmp': {'tmp_base_dir': '/tmp/myapp'},
+            'full_tmp_path': '{paths.tmp.tmp_base_dir}/session',
         },
         'logging': {
             'log_dir': '{paths.config_dir}/logs',
-            'tmp_base_path': '/var/tmp',
+            'tmp_base_dir': '/var/tmp',
             # Should resolve within this section if key exists:
-            'temp_dir': '{tmp_base_path}',
+            'temp_dir': '{tmp_base_dir}',
         },
     }
 
     expected = {
         'server': {'name': 'example.com', 'url': 'https://example.com'},
         'paths': {
             'config_dir': '/etc/myapp',
-            'tmp': {'tmp_base_path': '/tmp/myapp'},
+            'tmp': {'tmp_base_dir': '/tmp/myapp'},
             'full_tmp_path': '/tmp/myapp/session',
         },
         'logging': {
             'log_dir': '/etc/myapp/logs',
-            'tmp_base_path': '/var/tmp',
+            'tmp_base_dir': '/var/tmp',
             'temp_dir': '/var/tmp',
         },
     }
@@ -69,7 +70,7 @@ def test_unresolved_key_in_config():
         'server': {'name': 'example.com', 'url': 'https://{server.name}'},
         'paths': {
             'config_dir': '/etc/myapp',
-            'tmp': {'tmp_base_path': '/tmp/myapp'},
+            'tmp': {'tmp_base_dir': '/tmp/myapp'},
             # 'session' is missing in this section
             'full_tmp_path': '{paths.tmp.session}/session',
         },
@@ -148,18 +149,18 @@ def test_chained_placeholder_resolution():
     data = {
         'paths': {
             'tmp': {
-                'tmp_base_path': '/tmp/docbuild',
-                'tmp_path': '{tmp_base_path}/doc-example-com',
-                'tmp_deliverable_path': '{tmp_path}/deliverable/',
+                'tmp_base_dir': '/tmp/docbuild',
+                'tmp_dir': '{tmp_base_dir}/doc-example-com',
+                'tmp_deliverable_dir': '{tmp_dir}/deliverable/',
             },
         },
     }
 
-    result = replace_placeholders(data)
+    result: dict[str, Any] = replace_placeholders(data)
     tmp = result['paths']['tmp']
-    assert tmp['tmp_base_path'] == '/tmp/docbuild'
-    assert tmp['tmp_path'] == '/tmp/docbuild/doc-example-com'
-    assert tmp['tmp_deliverable_path'] == '/tmp/docbuild/doc-example-com/deliverable/'
+    assert tmp['tmp_base_dir'] == '/tmp/docbuild'
+    assert tmp['tmp_dir'] == '/tmp/docbuild/doc-example-com'
+    assert tmp['tmp_deliverable_dir'] == '/tmp/docbuild/doc-example-com/deliverable/'
 
 
 def test_too_many_nested_placeholder_expansions():
@@ -178,12 +179,12 @@ def test_too_many_nested_placeholder_expansions():
 def test_chained_cross_section_placeholders():
     config = {
         'build': {
-            'output': '{paths.tmp_deliverable_path}',
+            'output': '{paths.tmp_deliverable_dir}',
         },
         'paths': {
-            'tmp_base_path': '/tmp/docbuild',
-            'tmp_path': '{tmp_base_path}/doc-example-com',
-            'tmp_deliverable_path': '{paths.tmp_path}/deliverable/',
+            'tmp_base_dir': '/tmp/docbuild',
+            'tmp_dir': '{tmp_base_dir}/doc-example-com',
+            'tmp_deliverable_dir': '{paths.tmp_dir}/deliverable/',
         },
     }
 

tests/conftest.py

@@ -49,8 +49,8 @@ def env_content(default_env_config_filename: Path) -> Path:
 temp_repo_dir = "/data/docserv/repos/temporary-branches/"
 
 [paths.tmp]
-tmp_base_path = "/tmp"
-tmp_path = "{tmp_base_path}/doc-example-com"
+tmp_base_dir = "/tmp"
+tmp_path = "{tmp_base_dir}/doc-example-com"
 """
     default_env_config_filename.write_text(content)
     return default_env_config_filename