docs: add environment config reference and user guide for config subc… (#156)

* docs: add environment config reference and user guide for config subcommand (#110)

Signed-off-by: sushant-suse <[email protected]>

* docs: added fragment file, updated ruff checks

Signed-off-by: sushant-suse <[email protected]>

* docs: updated the descriptions of subcommands

Signed-off-by: sushant-suse <[email protected]>

---------

Signed-off-by: sushant-suse <[email protected]>

Author: sushant-suse

changelog.d/110.doc.rst

@@ -0,0 +1 @@
+Added a comprehensive technical reference for environment configuration keys and a User Guide section for the ``docbuild config env`` subcommand.

docs/source/reference/_autoapi/docbuild/models/config/env/EnvBuildContainer.rst

@@ -17,3 +17,12 @@ docbuild.models.config.env.EnvBuildContainer
       Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].
 
 
+
+   .. py:attribute:: container
+      :type:  str
+      :value: None
+
+
+      The container image used for the build environment.
+
+

docs/source/reference/_autoapi/docbuild/models/config/env/EnvBuildDaps.rst

@@ -17,3 +17,21 @@ docbuild.models.config.env.EnvBuildDaps
       Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].
 
 
+
+   .. py:attribute:: command
+      :type:  str
+      :value: None
+
+
+      The base command used for DAPS execution.
+
+
+
+   .. py:attribute:: meta
+      :type:  str
+      :value: None
+
+
+      The command used to extract DAPS metadata.
+
+

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

@@ -100,7 +100,7 @@ docbuild.models.config.env.EnvPathsConfig
 
 
    .. py:attribute:: base_tmp_dir
-      :type:  pathlib.Path
+      :type:  docbuild.models.path.EnsureWritableDirectory
       :value: None
 
 

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

@@ -32,6 +32,6 @@ docbuild.models.config.env.EnvTargetPaths
       :value: None
 
 
-      Directory for backups.
+      Local directory for storing build backups before deployment.
 
 

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

@@ -28,7 +28,7 @@ docbuild.models.config.env.EnvTmpPaths
 
 
    .. py:attribute:: tmp_dir
-      :type:  pathlib.Path
+      :type:  docbuild.models.path.EnsureWritableDirectory
       :value: None
 
 
@@ -37,7 +37,7 @@ docbuild.models.config.env.EnvTmpPaths
 
 
    .. py:attribute:: tmp_deliverable_dir
-      :type:  pathlib.Path
+      :type:  docbuild.models.path.EnsureWritableDirectory
       :value: None
 
 
@@ -46,7 +46,7 @@ docbuild.models.config.env.EnvTmpPaths
 
 
    .. py:attribute:: tmp_metadata_dir
-      :type:  pathlib.Path
+      :type:  docbuild.models.path.EnsureWritableDirectory
       :value: None
 
 
@@ -64,7 +64,7 @@ docbuild.models.config.env.EnvTmpPaths
 
 
    .. py:attribute:: tmp_out_dir
-      :type:  pathlib.Path
+      :type:  docbuild.models.path.EnsureWritableDirectory
       :value: None
 
 
@@ -73,7 +73,7 @@ docbuild.models.config.env.EnvTmpPaths
 
 
    .. py:attribute:: log_dir
-      :type:  pathlib.Path
+      :type:  docbuild.models.path.EnsureWritableDirectory
       :value: None
 
 

docs/source/user/config.rst

@@ -32,3 +32,15 @@ To deal with different environments without having to type the full command each
    alias docbuild-prod='docbuild --env-config env.production.toml'
    alias docbuild-test='docbuild --env-config env.testing.toml'
    alias docbuild-dev='docbuild --env-config env.devel.toml'
+
+Viewing the Environment Configuration
+------------------------------------
+
+To see how ``docbuild`` interprets your environment configuration, use the ``config env`` subcommand. This is particularly useful for verifying that all placeholders (like ``{{product}}`` or ``{{lang}}``) have been correctly resolved into absolute paths.
+
+.. code-block:: shell-session
+   :caption: Displaying the resolved environment configuration
+
+   docbuild config env
+
+If the configuration contains errors—such as missing mandatory keys or invalid data types—the command will output a validation error detailing what needs to be fixed.

src/docbuild/models/config/env.py

@@ -43,19 +43,37 @@
 class EnvBuildDaps(BaseModel):
     """Configuration for daps command execution."""
 
-    # Allows extra keys from the TOML file that aren't yet defined in the model schema.
     model_config = ConfigDict(extra="allow")
 
-    command: str = Field(..., description="The base daps command.")
-    meta: str = Field(..., description="The daps metadata command.")
+    command: str = Field(
+        ...,
+        title="DAPS Command",
+        description="The base daps command executable.",
+        examples=["daps"]
+    )
+    "The base command used for DAPS execution."
+
+    meta: str = Field(
+        ...,
+        title="DAPS Metadata Subcommand",
+        description="The daps metadata command for extracting info.",
+        examples=["daps metadata"]
+    )
+    "The command used to extract DAPS metadata."
 
 
 class EnvBuildContainer(BaseModel):
     """Configuration for container usage."""
 
     model_config = ConfigDict(extra="allow")
 
-    container: str = Field(..., description="The container registry path/name.")
+    container: str = Field(
+        ...,
+        title="Container Image",
+        description="The container registry path or image name.",
+        examples=["registry.opensuse.org/documentation/containers/15.6/opensuse-daps-toolchain:latest"]
+    )
+    "The container image used for the build environment."
 
 
 class EnvBuild(BaseModel):
@@ -175,9 +193,7 @@ class EnvTmpPaths(BaseModel):
 
     tmp_deliverable_dir: EnsureWritableDirectory = Field(
         title="Temporary Deliverable Directory",
-        description=(
-            "The directory where deliverable repositories are cloned and processed."
-        ),
+        description="The directory where deliverable repositories are cloned and processed.",
         examples=["/var/tmp/docbuild/doc-example-com/deliverable/"],
     )
     "Directory for temporary deliverable clones."
@@ -191,9 +207,7 @@ class EnvTmpPaths(BaseModel):
 
     tmp_build_dir: str = Field(
         title="Temporary Build Directory",
-        description=(
-            "Temporary directory for intermediate files (contains placeholders)."
-        ),
+        description="Temporary directory for intermediate files (contains placeholders).",
         examples=[
             "/var/tmp/docbuild/doc-example-com/build/{{product}}-{{docset}}-{{lang}}"
         ],
@@ -202,10 +216,7 @@ class EnvTmpPaths(BaseModel):
 
     tmp_out_dir: EnsureWritableDirectory = Field(
         title="Temporary Output Directory",
-        description=(
-            "The final temporary directory where built artifacts land before "
-            "deployment."
-        ),
+        description="The final temporary directory where built artifacts land before deployment.",
         examples=["/var/tmp/docbuild/doc-example-com/out/"],
     )
     "Temporary final output directory."
@@ -242,11 +253,10 @@ class EnvTargetPaths(BaseModel):
 
     backup_dir: Path = Field(
         title="Build Server Backup Directory",
-        description=(
-            "The location on the build server before it is synced to the target path."
-        ),
+        description="The location on the build server before it is synced to the target path.",
+        examples=["/var/lib/docbuild/backups"]
     )
-    "Directory for backups."
+    "Local directory for storing build backups before deployment."
 
 
 class EnvPathsConfig(BaseModel):
@@ -256,20 +266,14 @@ class EnvPathsConfig(BaseModel):
 
     config_dir: Path = Field(
         title="Configuration Directory",
-        description=(
-            "The configuration directory containing application and environment "
-            "files (e.g. app.toml)"
-        ),
+        description="The configuration directory containing application and environment files (e.g. app.toml).",
         examples=["/etc/docbuild"],
     )
     "Path to configuration files."
 
     root_config_dir: Path = Field(
         title="Root Configuration Directory",
-        description=(
-            "The highest-level configuration directory containing common "
-            "configuration files."
-        ),
+        description="The highest-level directory containing common config files.",
         examples=["/etc/docbuild"],
     )
     "Path to the root configuration files."
@@ -283,10 +287,7 @@ class EnvPathsConfig(BaseModel):
 
     server_rootfiles_dir: Path = Field(
         title="Server Root Files Directory",
-        description=(
-            "Directory for files that should be placed in the root of the "
-            "server deployment."
-        ),
+        description="Files placed in the root of the server deployment.",
         examples=["/etc/docbuild/server-root-files-doc-suse-com"],
     )
     "Path for server root files."
@@ -300,10 +301,7 @@ class EnvPathsConfig(BaseModel):
 
     tmp_repo_dir: Path = Field(
         title="Temporary Repository Directory",
-        description=(
-            "The directory used for temporary working copies cloned from "
-            "the permanent bare repositories."
-        ),
+        description="Directory used for temporary working copies cloned from permanent bare repos.",
         examples=["/var/cache/docbuild/repos/temporary-branches/"],
     )
     "Directory for temporary working copies."
@@ -324,19 +322,14 @@ class EnvPathsConfig(BaseModel):
 
     meta_cache_dir: Path = Field(
         title="Metadata Cache Directory",
-        description=(
-            "Cache directory specifically for repository and deliverable metadata."
-        ),
+        description="Cache specifically for repository and deliverable metadata.",
         examples=["/var/cache/docbuild/doc-example-com/meta"],
     )
     "Metadata cache path."
 
     base_tmp_dir: EnsureWritableDirectory = Field(
         title="Base Temporary Directory (System Wide)",
-        description=(
-            "The root directory for all temporary artifacts (used for "
-            "placeholder resolution)."
-        ),
+        description="The root directory for all temporary artifacts (used for placeholder resolution).",
         examples=["/var/tmp/docbuild"],
     )
     "Base system temporary path."