From faf8d3fed5a9150d3ad5430c28edd98960c06fa2 Mon Sep 17 00:00:00 2001 From: luisquix <120378585+luisquix@users.noreply.github.com> Date: Tue, 3 Sep 2024 15:35:55 +0200 Subject: [PATCH] Fix some formatting issues (#63) --- docs/yaml-reference/app-descriptor.md | 17 +++++++---- docs/yaml-reference/pipeline-descriptor.md | 34 +++++++++++----------- mkdocs.yml | 4 +-- 3 files changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/yaml-reference/app-descriptor.md b/docs/yaml-reference/app-descriptor.md index a56c939..a252807 100644 --- a/docs/yaml-reference/app-descriptor.md +++ b/docs/yaml-reference/app-descriptor.md @@ -1,4 +1,3 @@ - # Application YAML Descriptor (app.yaml) The `app.yaml` file is used to define the configuration of a Quix application. This file serves as a contract for the application, outlining its variables and settings. It is similar to deployment configurations, but specific to the application itself. @@ -11,7 +10,7 @@ The `app.yaml` file is used to define the configuration of a Quix application. T name: Slack Alerts language: python ``` -a + **Explanation:** - **name:** The name of the application. This should be a clear and descriptive identifier that reflects the application's purpose. @@ -53,10 +52,14 @@ variables: - **name:** The name of the variable, which identifies it within the application. - **inputType:** Defines the type of input expected. This can be: - - `InputTopic`: Refers to a topic that the application will consume data from. - - `OutputTopic`: Refers to a topic where the application will produce data. - - `Secret`: Refers to a sensitive piece of information, such as API keys or webhook URLs, that needs to be securely handled. - - `FreeText`: A flexible text input that can be used for various settings or parameters. + + - `InputTopic`: Refers to a topic that the application will consume data from. + + - `OutputTopic`: Refers to a topic where the application will produce data. + + - `Secret`: Refers to a sensitive piece of information, such as API keys or webhook URLs, that needs to be securely handled. + + - `FreeText`: A flexible text input that can be used for various settings or parameters. - **description:** A brief explanation of the variable's purpose and how it should be used. @@ -91,7 +94,9 @@ Changes to the `app.yaml` file should be made thoughtfully, as they can affect a ## Best Practices - **Consistent Naming:** Ensure that variable names are clear and descriptive to avoid confusion during deployment. +- - **Security:** Handle `Secret` type variables with care to ensure sensitive information is not exposed. +- - **Documentation:** Keep the `description` field updated to accurately reflect the purpose and usage of each variable. By managing your `app.yaml` file effectively, you can ensure that your application is deployed consistently and operates reliably in various environments, while retaining the flexibility to adapt or remove elements as needed. diff --git a/docs/yaml-reference/pipeline-descriptor.md b/docs/yaml-reference/pipeline-descriptor.md index 46b0eb5..a91f91a 100644 --- a/docs/yaml-reference/pipeline-descriptor.md +++ b/docs/yaml-reference/pipeline-descriptor.md @@ -70,27 +70,27 @@ deployments: - **version:** Indicates the version of the application to deploy. Using `latest` ensures that the most recent version is deployed, but this can be set to a specific version to ensure consistency. You can also use a commit reference in order to have a specific version. - **resources:** Defines the compute resources allocated to the deployment. This includes: - - **cpu:** The amount of CPU resources allocated (in millicores). - - **memory:** The amount of memory allocated (in megabytes). - - **replicas:** The number of instances of the application to run for scalability and fault tolerance. + - **cpu:** The amount of CPU resources allocated (in millicores). + - **memory:** The amount of memory allocated (in megabytes). + - **replicas:** The number of instances of the application to run for scalability and fault tolerance. - **desiredStatus:** The state in which you want the application to be. Common statuses include `Running` and `Stopped`. - **publicAccess:** Configures the public accessibility of the deployment. If enabled, the service will be accessible via a public URL. - - **enabled:** A boolean value that determines if public access is enabled (`true` or `false`). - - **urlPrefix:** The URL prefix under which the service will be accessible. + - **enabled:** A boolean value that determines if public access is enabled (`true` or `false`). + - **urlPrefix:** The URL prefix under which the service will be accessible. - **network:** Defines the network settings for the deployment, including the exposed ports. - - **ports:** A list of ports to expose. - - **port:** The external port number that will be exposed. - - **targetPort:** The internal port number the traffic will be directed to. + - **ports:** A list of ports to expose. + - **port:** The external port number that will be exposed. + - **targetPort:** The internal port number the traffic will be directed to. - **variables:** Defines any configurable parameters for the deployment. These are typically inputs or outputs such as: - - **name:** The name of the variable. - - **inputType:** The type of input, usually `InputTopic`, `OutputTopic`, `Secret`, or `FreeText`. - - **description:** A brief explanation of what this variable does. - - **required:** Indicates whether this variable must be provided (`true` or `false`). - - **value:** The default or specified value for this variable. + - **name:** The name of the variable. + - **inputType:** The type of input, usually `InputTopic`, `OutputTopic`, `Secret`, or `FreeText`. + - **description:** A brief explanation of what this variable does. + - **required:** Indicates whether this variable must be provided (`true` or `false`). + - **value:** The default or specified value for this variable. ### 3. Topics @@ -116,10 +116,10 @@ topics: - **persisted:** A boolean value that indicates whether the data in this topic should be stored persistently. Setting this to `false` means data will not be stored permanently and might be deleted after processing. - **configuration:** (Optional) This section allows you to fine-tune how the topic behaves. Common configurations include: - - **partitions:** The number of partitions within the topic. More partitions allow for greater parallelism but may complicate data ordering. - - **retentionInMinutes:** How long the data should be retained in the topic before being deleted or compacted. - - **retentionInBytes:** The total size of data that the topic can retain. When this limit is reached, older data is deleted. - - **cleanupPolicy:** Defines how the topic handles old data. `Delete` means old data is removed, whereas other policies like `Compact` could be used for different use cases. + - **partitions:** The number of partitions within the topic. More partitions allow for greater parallelism but may complicate data ordering. + - **retentionInMinutes:** How long the data should be retained in the topic before being deleted or compacted. + - **retentionInBytes:** The total size of data that the topic can retain. When this limit is reached, older data is deleted. + - **cleanupPolicy:** Defines how the topic handles old data. `Delete` means old data is removed, whereas other policies like `Compact` could be used for different use cases. ## How to Use the `quix.yaml` File diff --git a/mkdocs.yml b/mkdocs.yml index c820aaf..bcd7b61 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,8 +60,8 @@ nav: - 'How-To guides': - 'Using the CLI with GitHub Actions': 'How-To/cli-github-actions.md' - Yaml Reference: - - 'Pipeline YAML descriptor (quix.yaml)': 'yaml-reference/pipeline-descriptor.md' - - 'Application YAML descriptor (app.yaml)': 'yaml-reference/app-descriptor.md' + - 'Pipeline YAML (quix.yaml)': 'yaml-reference/pipeline-descriptor.md' + - 'Application YAML (app.yaml)': 'yaml-reference/app-descriptor.md' - CLI Reference: - Cloud Commands: - cli-reference/cloud/index.md