Skip to content

Commit cbf5601

Browse files
sushant-susesushant-suse
authored
refactor: standardize env config keys to use tmp_ and _dir (#153)
* refactor: standardize env config keys to use tmp_ and _dir * docs: regenerate API references, reverted Path, added comment in toml, rename changelog to breaking * refactor: reverted EnvGeneralConfig Signed-off-by: sushant-suse <[email protected]> --------- Signed-off-by: sushant-suse <[email protected]>
1 parent adbc42a commit cbf5601

12 files changed

Lines changed: 93 additions & 97 deletions

File tree

‎changelog.d/102.breaking.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Standardized environment configuration keys in ``env.toml``.
2+
All temporary paths now use the ``tmp_`` prefix (for example, ``tmp_repo_dir`` instead of ``temp_repo_dir``).
3+
All directory-related keys now consistently use the ``_dir`` suffix, and previous ``_path`` aliases have been removed.

‎docs/source/reference/_autoapi/docbuild/constants/index.rst‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Attributes
1919
docbuild.constants.ALLOWED_LANGUAGES
2020
docbuild.constants.DEFAULT_DELIVERABLES
2121
docbuild.constants.SERVER_ROLES
22+
docbuild.constants.SERVER_ROLES_ALIASES
2223
docbuild.constants.DEFAULT_LIFECYCLE
2324
docbuild.constants.ALLOWED_LIFECYCLES
2425
docbuild.constants.VALID_PRODUCTS
@@ -74,7 +75,14 @@ Module Contents
7475

7576
.. py:data:: SERVER_ROLES
7677
77-
The different server roles, including long and short spelling.
78+
The unique primary server role values.
79+
80+
81+
.. py:data:: SERVER_ROLES_ALIASES
82+
:value: ('PRODUCTION', 'STAGING', 'TESTING', 'PROD', 'P', 'prod', 'p', 'STAGE', 'S', 'stage', 's',...
83+
84+
85+
All valid server role names and aliases for validation and testing.
7886

7987

8088
.. py:data:: DEFAULT_LIFECYCLE

‎docs/source/reference/_autoapi/docbuild/models/config/env/EnvPathsConfig.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,12 @@ docbuild.models.config.env.EnvPathsConfig
6363

6464

6565

66-
.. py:attribute:: temp_repo_dir
66+
.. py:attribute:: tmp_repo_dir
6767
:type: pathlib.Path
6868
:value: None
6969

7070

71-
Path for temporary working copies.
71+
Directory for temporary working copies.
7272

7373

7474

@@ -100,7 +100,7 @@ docbuild.models.config.env.EnvPathsConfig
100100

101101

102102
.. py:attribute:: base_tmp_dir
103-
:type: docbuild.models.path.EnsureWritableDirectory
103+
:type: pathlib.Path
104104
:value: None
105105

106106

‎docs/source/reference/_autoapi/docbuild/models/config/env/EnvTargetPaths.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,20 @@ docbuild.models.config.env.EnvTargetPaths
1818

1919

2020

21-
.. py:attribute:: target_path
21+
.. py:attribute:: target_dir
2222
:type: str
2323
:value: None
2424

2525

26-
The destination path for final built documentation.
26+
The destination directory for final built documentation.
2727

2828

2929

30-
.. py:attribute:: backup_path
30+
.. py:attribute:: backup_dir
3131
:type: pathlib.Path
3232
:value: None
3333

3434

35-
Path for backups.
35+
Directory for backups.
3636

3737

‎docs/source/reference/_autoapi/docbuild/models/config/env/EnvTmpPaths.rst‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,26 +27,26 @@ docbuild.models.config.env.EnvTmpPaths
2727

2828

2929

30-
.. py:attribute:: tmp_path
31-
:type: docbuild.models.path.EnsureWritableDirectory
30+
.. py:attribute:: tmp_dir
31+
:type: pathlib.Path
3232
:value: None
3333

3434

35-
General temporary path.
35+
General temporary directory.
3636

3737

3838

39-
.. py:attribute:: tmp_deliverable_path
40-
:type: docbuild.models.path.EnsureWritableDirectory
39+
.. py:attribute:: tmp_deliverable_dir
40+
:type: pathlib.Path
4141
:value: None
4242

4343

44-
Path for temporary deliverable clones.
44+
Directory for temporary deliverable clones.
4545

4646

4747

4848
.. py:attribute:: tmp_metadata_dir
49-
:type: docbuild.models.path.EnsureWritableDirectory
49+
:type: pathlib.Path
5050
:value: None
5151

5252

@@ -63,21 +63,21 @@ docbuild.models.config.env.EnvTmpPaths
6363

6464

6565

66-
.. py:attribute:: tmp_out_path
67-
:type: docbuild.models.path.EnsureWritableDirectory
66+
.. py:attribute:: tmp_out_dir
67+
:type: pathlib.Path
6868
:value: None
6969

7070

71-
Temporary final output path.
71+
Temporary final output directory.
7272

7373

7474

75-
.. py:attribute:: log_path
76-
:type: docbuild.models.path.EnsureWritableDirectory
75+
.. py:attribute:: log_dir
76+
:type: pathlib.Path
7777
:value: None
7878

7979

80-
Path for log files.
80+
Directory for log files.
8181

8282

8383

‎docs/source/reference/_autoapi/docbuild/models/doctype/Doctype.rst‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -125,14 +125,6 @@ docbuild.models.doctype.Doctype
125125

126126

127127

128-
.. py:method:: coerce_lifecycle(value: str | docbuild.models.lifecycle.LifecycleFlag) -> docbuild.models.lifecycle.LifecycleFlag
129-
:classmethod:
130-
131-
132-
Convert a string into a LifecycleFlag.
133-
134-
135-
136128
.. py:method:: coerce_langs(value: str | list[str | docbuild.models.language.LanguageCode]) -> list[docbuild.models.language.LanguageCode]
137129
:classmethod:
138130

@@ -166,3 +158,19 @@ docbuild.models.doctype.Doctype
166158
deliverables that match this Doctype.
167159

168160

161+
162+
.. py:method:: product_xpath_segment() -> str
163+
164+
Return the XPath segment for the product node.
165+
166+
Example: "product[@productid='sles']" or "product"
167+
168+
169+
170+
.. py:method:: docset_xpath_segment(docset: str) -> str
171+
172+
Return the XPath segment for the docset node.
173+
174+
Example: "docset[@setid='15-SP6']" or "docset"
175+
176+

‎docs/source/reference/_autoapi/docbuild/models/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Submodules
2020
/reference/_autoapi/docbuild/models/doctype/index
2121
/reference/_autoapi/docbuild/models/language/index
2222
/reference/_autoapi/docbuild/models/lifecycle/index
23+
/reference/_autoapi/docbuild/models/manifest/index
2324
/reference/_autoapi/docbuild/models/metadata/index
2425
/reference/_autoapi/docbuild/models/path/index
2526
/reference/_autoapi/docbuild/models/product/index

‎docs/source/reference/_autoapi/docbuild/models/lifecycle/LifecycleFlag.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ docbuild.models.lifecycle.LifecycleFlag
4444

4545

4646

47-
.. py:method:: from_str(value: str) -> LifecycleFlag
47+
.. py:method:: from_str(value: str) -> Self
4848
:classmethod:
4949

5050

‎docs/source/reference/_autoapi/docbuild/models/serverroles/ServerRole.rst‎

Lines changed: 1 addition & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -11,27 +11,5 @@ docbuild.models.serverroles.ServerRole
1111

1212
The server role.
1313

14-
15-
.. py:attribute:: PRODUCTION
16-
:value: 'production'
17-
18-
19-
Server is in production mode, serving live traffic.
20-
21-
22-
23-
.. py:attribute:: STAGING
24-
:value: 'staging'
25-
26-
27-
Server is in staging mode, used for testing before production.
28-
29-
30-
31-
.. py:attribute:: TESTING
32-
:value: 'testing'
33-
34-
35-
Server is in testing mode, used for development and QA.
36-
14+
This Enum supports various aliases and case variations for each role.
3715

‎etc/docbuild/env.example.toml‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ canonical_url_domain = "https://docs.example.com"
2929
[paths]
3030
# Section "paths": Defines several paths
3131
# Paths can hold placeholders in brackets.
32+
# Key naming convention:
33+
# * Suffix "_dir": contains only directory paths
34+
# * Suffix "_path": contains directory and filename paths
3235
root_config_dir = "/etc/docbuild"
3336
jinja_dir = "{root_config_dir}/jinja-doc-suse-com"
3437
config_dir = "{root_config_dir}/config.d"
@@ -38,10 +41,11 @@ base_cache_dir = "/var/cache/docserv"
3841
base_server_cache_dir = "{base_cache_dir}/{server.name}"
3942
base_tmp_dir = "/var/tmp/docbuild"
4043
repo_dir = "/data/docserv/repos/permanent-full/"
41-
temp_repo_dir = "/data/docserv/repos/temporary-branches/"
44+
tmp_repo_dir = "/data/docserv/repos/temporary-branches/"
4245
# cache_dir = "{base_cache_dir}/{server.name}"
4346
meta_cache_dir = "{base_cache_dir}/{server.name}/meta"
4447

48+
4549
[paths.tmp]
4650
# Section "paths.tmp": Definies temporary paths
4751
# Paths can hold placeholders in brackets.
@@ -54,6 +58,7 @@ tmp_out_dir = "{tmp_dir}/out/"
5458
log_dir = "{tmp_dir}/log/"
5559
tmp_deliverable_name = "{{product}}_{{docset}}_{{lang}}_XXXXXX"
5660

61+
5762
[paths.target]
5863
# Section "paths.target": Definies target paths
5964
target_dir = "[email protected]:/srv/docs"
@@ -63,6 +68,7 @@ backup_dir = "/data/docbuild/external-builds/"
6368
[build]
6469
# Section "build": General build parameters, independant from any specific
6570

71+
6672
[build.daps]
6773
# Section "build.daps": Configuration for daps
6874
command = "daps -vv"
@@ -75,6 +81,7 @@ meta = "daps -vv metadata --output {{output}}"
7581
# Section "build.container": Configuration for container
7682
container = "registry.opensuse.org/documentation/containers/15.6/opensuse-daps-toolchain:latest"
7783

84+
7885
[xslt-params]
7986
# Section "xslt-params": Replaces /etc/docserv/xslt-params-doc-suse-com.txt file
8087
# These keys are considered as XSLT parameters and passed

0 commit comments

Comments
 (0)