fix: improve wordings and punctuation

tdp/cli/__main__.py

@@ -43,7 +43,7 @@ def load_env(ctx: click.Context, param: click.Parameter, value: Path) -> Optiona
     envvar="TDP_ENV",
     callback=load_env,
     type=Path,
-    help="Path to environment configuration file",
+    help="Path to environment configuration file.",
 )
 @click.option(
     "--log-level",

tdp/cli/commands/browse.py

@@ -37,14 +37,14 @@
     envvar="TDP_LIMIT",
     type=int,
     default=15,
-    help="Limit number of deployments returned",
+    help="Limit number of deployments returned.",
 )
 @click.option(
     "--offset",
     envvar="TDP_OFFSET",
     type=int,
     default=0,
-    help="At which offset should the database query should start",
+    help="At which offset the database query should start.",
 )
 @database_dsn
 def browse(
@@ -94,7 +94,7 @@ def _print_deployments(deployments: Iterable[DeploymentModel]) -> None:
     """Print a list of deployments in a human readable format.
 
     Args:
-        deployments: List of deployments to print
+        deployments: List of deployments to print.
     """
     if not deployments:
         click.echo("No deployment found")
@@ -109,7 +109,7 @@ def _print_deployment(deployment: DeploymentModel) -> None:
     """Print a deployment in a human readable format.
 
     Args:
-        deployment: Deployment to print
+        deployment: Deployment to print.
     """
     if not deployment:
         click.echo("Deployment does not exist.")
@@ -122,7 +122,7 @@ def _print_operations(operations: list[OperationModel]) -> None:
     """Print a list of operations in a human readable format.
 
     Args:
-        operation: Operation to print
+        operation: Operation to print.
     """
     # Print general operation infos
     click.secho("Operation(s) details", bold=True)

tdp/cli/commands/dag.py

@@ -24,38 +24,38 @@
     "-t",
     "--transitive-reduction",
     is_flag=True,
-    help="Apply a transitive reduction on the DAG",
+    help="Apply a transitive reduction on the DAG.",
 )
 @click.option(
     "-g",
     "--glob",
     "pattern_format",
     flag_value="glob",
-    help="Each node argument will be process as glob pattern",
+    help="Each node argument will be process as glob pattern.",
 )
 @click.option(
     "-r",
     "--regex",
     "pattern_format",
     flag_value="regex",
-    help="Each node argument will be process as regex pattern",
+    help="Each node argument will be process as regex pattern.",
 )
 @click.option(
     "-ct",
     "--color-to",
-    help="List of node to color to, separated with a comma (,)",
+    help="List of nodes to color to, separated by commas (,).",
 )
 @click.option(
     "-cf",
     "--color-from",
-    help="Nodes that will be colored after applying get_operations_to_nodes, separed with a comma (,)",
+    help="List of nodes to color from after applying `--color-to`, separed by commas (,).",
     type=str,
 )
 @click.option(
     "-c",
     "--cluster",
     is_flag=True,
-    help="Group node into cluster inside each service",
+    help="Group nodes into cluster inside each service.",
 )
 @collections
 def dag(
@@ -86,7 +86,7 @@ def dag(
                 else:
                     raise ValueError("pattern_format invalid")
             if not nodes_expanded:
-                raise ValueError(f"No nodes found with {nodes}")
+                raise ValueError(f"No nodes found with {nodes}.")
             nodes = nodes_expanded
 
         # Nx ancestors only returns the ancestor, and node the selected node
@@ -120,7 +120,7 @@ def import_show():
         if importlib.util.find_spec(package) is None:
             raise click.ClickException(
                 "You need to install the 'visualization' extras to be able to use the "
-                + "dag command. Run 'poetry install --extras visualization'."
+                + "`tdp dag` command. Run `poetry install --extras visualization`."
             )
 
     from tdp.core.dag_dot import show

tdp/cli/commands/default_diff.py

@@ -35,11 +35,11 @@ def default_diff(collections: Collections, vars: Path, service: Optional[str] =
 
 
 def service_diff(collections, service):
-    """computes the difference between the default variables from a service, and the variables from your service variables inside your tdp_vars
+    """Computes the difference between the default variables from a service, and the variables from your service variables inside your tdp_vars.
 
     Args:
-        collections (Collections): Collections object
-        service (ServiceManager): service to compare's manager
+        collections (Collections): Collections object.
+        service (ServiceManager): Service to compare's manager.
     """
     # key: filename with extension, value: PosixPath(filepath)
     default_service_vars_paths = OrderedDict()
@@ -109,15 +109,15 @@ def service_diff(collections, service):
 def compute_and_print_difference(
     service_name, filename, left_content, right_content, left_path, right_path
 ):
-    """computes differences between 2 files, and outputs them.
+    """Computes differences between 2 files, and outputs them.
 
     Args:
-        service_name (str): name of the service
-        filename (str): name of the file to display
-        left_content (Iterator[str]): content to compare from
-        right_content (Iterator[str]): content to compare to
-        left_path (str): filename to compare from, to use as contextual information
-        right_path (str): filename to compare to, to use as contextual information
+        service_name (str): Name of the service.
+        filename (str): Name of the file to display.
+        left_content (Iterator[str]): Content to compare from.
+        right_content (Iterator[str]): Content to compare to.
+        left_path (str): Filename to compare from, to use as contextual information.
+        right_path (str): Filename to compare to, to use as contextual information.
     """
     differences = difflib.context_diff(
         left_content,

tdp/cli/commands/deploy.py

@@ -37,20 +37,20 @@
     is_flag=True,
     help="Force stale status update.",
 )
-@click.option("--dry", is_flag=True, help="Execute dag without running any action")
+@click.option("--dry", is_flag=True, help="Execute dag without running any action.")
 @collections
 @database_dsn
 @click.option(
     "--mock-deploy",
     envvar="TDP_MOCK_DEPLOY",
     is_flag=True,
-    help="Mock the deploy, do not actually run the ansible playbook",
+    help="Mock the deploy, do not actually run the ansible playbook.",
 )
 @click.option(
     "--run-directory",
     envvar="TDP_RUN_DIRECTORY",
     type=click.Path(resolve_path=True, path_type=Path, exists=True),
-    help="Working directory where the executor is launched (`ansible-playbook` for Ansible)",
+    help="Working directory where the executor is launched (`ansible-playbook` for Ansible).",
     required=True,
 )
 @validate

tdp/cli/commands/init.py

@@ -23,7 +23,7 @@
     required=False,
     type=click.Path(exists=True, resolve_path=True, path_type=Path),
     multiple=True,
-    help="Path to tdp vars overrides. Can be used multiple times. Last one takes precedence.",
+    help="Path to TDP variables overrides. Can be used multiple times. Last one takes precedence.",
 )
 @collections
 @database_dsn
@@ -36,7 +36,7 @@ def init(
     validate: bool,
     vars: Path,
 ):
-    """Initialize the database and the tdp vars."""
+    """Initialize the database and the TDP variables."""
     init_db(database_dsn)
     cluster_variables = ClusterVariables.initialize_cluster_variables(
         collections, vars, overrides, validate=validate

tdp/cli/commands/ops.py

@@ -37,7 +37,7 @@ def ops(
     """Display all available operations."""
     if topo_sort and not display_dag_operations:
         click.echo(
-            "Warning: '--topo-sort' can only be used with '--dag' or '--dag-operations'."
+            "Warning: `--topo-sort` can only be used with `--dag` or `--dag-operations`."
         )
 
     if display_dag_operations:

tdp/cli/commands/plan/dag.py

@@ -71,7 +71,7 @@ def _validate_filtertype(
 @click.option(
     "--stop",
     is_flag=True,
-    help="Replace 'start' operations by 'stop' operations. This option should be used with --reversed.",
+    help="Replace 'start' operations by 'stop' operations. This option should be used with `--reverse`.",
 )
 @preview
 @collections
@@ -90,7 +90,7 @@ def dag(
 ):
     """Deploy from the DAG."""
     if stop and restart:
-        click.UsageError("Cannot use --restart and --stop at the same time.")
+        click.UsageError("Cannot use `--restart` and `--stop` at the same time.")
     dag = Dag(collections)
     set_nodes = set()
     if sources:

tdp/cli/commands/plan/resume.py

@@ -38,7 +38,7 @@ def resume(
             click.echo("Creating a deployment plan to resume latest deployment.")
         else:
             deployment_to_resume = get_deployment(session, id)
-            click.echo(f"Creating a deployment plan to resume deployment #{id}.")
+            click.echo(f"Creating a deployment plan to resume deployment {id}.")
         deployment = DeploymentModel.from_failed_deployment(
             collections, deployment_to_resume
         )

tdp/cli/commands/playbooks.py

@@ -17,14 +17,14 @@
 @click.option(
     "--output-dir",
     type=Path,
-    help="Output dir where playbooks will be written",
+    help="Output directory where playbooks will be written.",
     required=False,
     default=".",
 )
 @click.option(
     "--for-collection",
     type=str,
-    help="Only write operation from this collection",
+    help="Only write operations from this collection.",
     required=False,
     multiple=True,
 )
@@ -47,7 +47,7 @@ def playbooks(services, output_dir, for_collection, collections):
         dag_service_operations.setdefault(operation.service_name, []).append(operation)
 
     if not nx.is_directed_acyclic_graph(dag_services):
-        raise RuntimeError("dag_services is not a DAG")
+        raise RuntimeError("dag_services is not a DAG.")
 
     def custom_key(node):
         operation_priority = SERVICE_PRIORITY.get(node, DEFAULT_SERVICE_PRIORITY)
@@ -61,7 +61,7 @@ def custom_key(node):
         for service in services:
             if service not in dag_services.nodes:
                 raise ValueError(
-                    f"Service '{service}' is not in the DAG, services available: {dag_services.nodes}"
+                    f"Service '{service}' is not in the DAG, services available: {dag_services.nodes}."
                 )
         # Reorder services specified with services DAG topological_sort order
         services = [

tdp/cli/commands/status/edit.py

@@ -64,7 +64,7 @@ def edit(
     """
     if to_config is not None and to_restart is not None:
         raise click.UsageError(
-            "You must provide either --to-config or --to-restart option."
+            "You must provide either `--to-config` or `--to-restart` option."
         )
 
     cluster_variables = ClusterVariables.get_cluster_variables(
@@ -78,7 +78,7 @@ def edit(
 
         # TODO: would be nice if host is optional and we can edit all hosts at once
         if not hosts:
-            raise click.UsageError("At least one --host is required.")
+            raise click.UsageError("At least one `--host` is required.")
 
         # Create a new SCHStatusLog for each host
         for host in hosts:

tdp/cli/commands/validate.py

@@ -19,6 +19,6 @@
 @collections
 @vars
 def validate(collections: Collections, vars: Path):
-    """Validate tdp vars against the loaded collections schemas."""
+    """Validate TDP variables against the loaded collections schemas."""
     ClusterVariables.get_cluster_variables(collections, vars, validate=True)
-    click.echo("TDP Vars are valid")
+    click.echo("TDP variables are valid")

tdp/cli/commands/vars/edit.py

@@ -33,8 +33,8 @@
     "--commit_message",
     "-c",
     type=str,
-    default="updated from tdp edit-vars command",
-    help="Validation message for the service repository",
+    default="updated from `tdp vars edit` command",
+    help="Validation message for the service repository.",
 )
 @collections
 @database_dsn
@@ -56,9 +56,9 @@ def edit(
 
     \b
     Examples:
-        tdp edit-vars hdfs
-        tdp edit-vars hdfs datanode --commit_message "updated datanode variables"
-        tdp edit-vars hdfs hdfs_datanode.yml
+        tdp vars edit hdfs
+        tdp vars edit hdfs datanode --commit_message "updated datanode variables"
+        tdp vars edit hdfs hdfs_datanode.yml
     """
     cluster_variables = ClusterVariables.get_cluster_variables(
         collections, vars, validate=validate
@@ -80,13 +80,13 @@ def edit(
     # Get the variable file to edit
     base_path = vars / service_name
     if service_component_parameter is None:
-        # tdp edit-vars service
+        # tdp vars edit service
         variables_file = base_path / (service_name + YML_EXTENSION)
     elif service_component_parameter.endswith(YML_EXTENSION):
-        # tdp edit-vars service service.yml OR tdp edit-vars service service_component.yml
+        # tdp vars edit service service.yml OR tdp vars edit service service_component.yml
         variables_file = base_path / service_component_parameter
     else:
-        # tdp edit-vars service component
+        # tdp vars edit service component
         variables_file = base_path / (
             service_name + "_" + service_component_parameter + YML_EXTENSION
         )

tdp/cli/queries.py

@@ -395,11 +395,11 @@ def get_deployments(session: Session, limit: int, offset: int) -> list[Deploymen
 
 
 def get_deployment(session: Session, deployment_id: int) -> DeploymentModel:
-    """Get a deployment by id.
+    """Get a deployment by ID.
 
     Args:
         session: The database session.
-        deployment_id: The deployment id.
+        deployment_id: The deployment ID.
 
     Returns:
         The deployment.
@@ -409,7 +409,7 @@ def get_deployment(session: Session, deployment_id: int) -> DeploymentModel:
     try:
         return session.query(DeploymentModel).filter_by(id=deployment_id).one()
     except NoResultFound as e:
-        raise Exception(f"Deployment id {deployment_id} does not exist.") from e
+        raise Exception(f"Deployment with ID {deployment_id} does not exist.") from e
 
 
 def get_last_deployment(session: Session) -> DeploymentModel:
@@ -454,7 +454,7 @@ def get_operation_records(
 
     Args:
         session: The database session.
-        deployment_id: The deployment id.
+        deployment_id: The deployment ID.
         operation_name: The operation name.
 
     Returns: