From a47e2a9d87081c668fcb5b5ce9d90bd52c14018f Mon Sep 17 00:00:00 2001 From: tischrei Date: Wed, 11 Jun 2025 08:02:59 +0000 Subject: [PATCH] README.md files added documenting the metadata dependencies and usage --- otc_metadata/data/documents/README.md | 69 +++++++++++++++++++ otc_metadata/data/repositories/README.md | 47 +++++++++++++ .../data/service_categories/README.md | 17 +++++ otc_metadata/data/services/README.md | 48 +++++++++++++ 4 files changed, 181 insertions(+) create mode 100644 otc_metadata/data/documents/README.md create mode 100644 otc_metadata/data/repositories/README.md create mode 100644 otc_metadata/data/service_categories/README.md create mode 100644 otc_metadata/data/services/README.md diff --git a/otc_metadata/data/documents/README.md b/otc_metadata/data/documents/README.md new file mode 100644 index 0000000..4c6944e --- /dev/null +++ b/otc_metadata/data/documents/README.md @@ -0,0 +1,69 @@ +# 📁 documents/ + +This folder contains metadata about documentation files per service, such as user guides or API references. Each file describes a single document variant for a specific cloud environment. + +## 🔧 Example: `ecs-umn.yaml` + +```yaml +--- +hc_location: usermanual/ecs +html_location: docs/ecs/umn +link: /elastic-cloud-server/umn/ +rst_location: umn/source +service_type: ecs +title: User Guide +type: umn +cloud_environments: + - name: eu_de + visibility: public + pdf_visibility: public + pdf_enabled: true + - name: swiss + visibility: public + pdf_visibility: public + pdf_enabled: true +``` + +## 🔧 Example: `ecs-api-ref.yaml` + +```yaml +--- +hc_location: api/ecs +html_location: docs/ecs/api-ref +link: /elastic-cloud-server/api-ref/ +rst_location: api-ref/source +service_type: ecs +title: API Reference +type: api-ref +cloud_environments: + - name: eu_de + visibility: public + pdf_visibility: public + pdf_enabled: true + - name: swiss + visibility: public + pdf_visibility: public + pdf_enabled: true +``` + +## Parameter Reference + +| Field | Type | Description | +| -------------------- | ------ | -------------------------------------------------------- | +| `hc_location` | string | Path used in the Horizon Console. | +| `html_location` | string | Location of the built HTML output. | +| `link` | string | Target URL segment for this document. | +| `rst_location` | string | Source folder for `.rst` input. | +| `service_type` | string | Related service identifier (matches `services/`). | +| `title` | string | Display name of the document. | +| `type` | string | Document type (e.g., `umn`, `api-ref`, etc.). | +| `cloud_environments` | list | Region-specific metadata like visibility or PDF support. | + +### `cloud_environments` Options: + +| Field | Type | Allowed Values | Description | +| ---------------- | ------- | ------------------------------ | ---------------------------------- | +| `name` | string | e.g., `eu_de`, `swiss` | Name of the cloud region. | +| `visibility` | string | `public`, `internal`, `hidden` | Document visibility level. | +| `pdf_visibility` | string | `public`, `internal`, `hidden` | PDF visibility level | +| `pdf_enabled` | boolean | `true`, `false` | Enable PDF export | diff --git a/otc_metadata/data/repositories/README.md b/otc_metadata/data/repositories/README.md new file mode 100644 index 0000000..00fd8a8 --- /dev/null +++ b/otc_metadata/data/repositories/README.md @@ -0,0 +1,47 @@ +# 📁 repositories/ + +Defines the documentation repositories associated with each service for both internal and public environments. Used for resolving documentation sources and CI sync jobs. + +## 🔧 Example: `aom.yaml` + +```yaml +--- +service_type: ecs +repositories: + - environment: public + repo: opentelekomcloud-docs/elastic-cloud-server + type: github + cloud_environments: + - eu_de + - environment: internal + repo: docs/elastic-cloud-server + type: gitea + cloud_environments: + - eu_de + - environment: public + repo: opentelekomcloud-docs-swiss/elastic-cloud-server + type: github + cloud_environments: + - swiss + - environment: internal + repo: docs-swiss/elastic-cloud-server + type: gitea + cloud_environments: + - swiss +``` + +## Parameter Options: + +| Field | Type | Description | +| -------------- | ------ | ---------------------------------------------------- | +| `service_type` | string | Links this configuration to a service (`services/`). | +| `repositories` | list | List of repositories per environment and cloud. | + +### `repositories` Options: + +| Field | Type | Allowed Values | Description | +| -------------------- | ------ | ---------------------- | ------------------------------------- | +| `environment` | string | `public`, `internal` | Visibility level of the repository. | +| `repo` | string | Git path | Path to the Git repository. | +| `type` | string | `github`, `gitea` | Type of Git service. | +| `cloud_environments` | list | e.g., `eu_de`, `swiss` | Supported regions for the repository. | diff --git a/otc_metadata/data/service_categories/README.md b/otc_metadata/data/service_categories/README.md new file mode 100644 index 0000000..d7f82cc --- /dev/null +++ b/otc_metadata/data/service_categories/README.md @@ -0,0 +1,17 @@ +# 📁 service_categories/ + +Contains the list of service category definitions. These categories help group services (e.g., "Application", "Database"). + +## 🔧 Example: `application.yaml` + +```yaml +name: application +title: Application +``` + +## Parameter Reference + +| Field | Type | Description | +| ------- | ------ | ------------------------------------- | +| `name` | string | Internal identifier for the category. | +| `title` | string | Display name used in UIs. | diff --git a/otc_metadata/data/services/README.md b/otc_metadata/data/services/README.md new file mode 100644 index 0000000..f4bd0d9 --- /dev/null +++ b/otc_metadata/data/services/README.md @@ -0,0 +1,48 @@ +# 📁 services/ + +This folder contains metadata files that describe individual cloud services. Each file defines a single service and its configuration across environments. + +## 🔧 Example: `ecs.yaml` + +```yaml +--- +service_category: compute +service_title: Elastic Cloud Server +service_type: ecs +service_uri: elastic-cloud-server +teams: + - name: docs-compute-rw + permission: write +cloud_environments: + - name: eu_de + visibility: public + - name: swiss + visibility: public +is_global: false +``` + +## Parameter Reference + +| Parameter | Type | Description | +| -------------------- | ------- | --------------------------------------------------------------------- | +| `is_global` | boolean | Indicates whether the service is available globally (`true`/`false`). | +| `service_category` | string | Category reference, defined in `service_categories/`. | +| `service_title` | string | Display name of the service. | +| `service_type` | string | Unique identifier used across all metadata. | +| `service_uri` | string | URI component used in documentation links. | +| `cloud_environments` | list | List of cloud regions and their visibility settings. | +| `teams` | list | Contributor teams with write or read access. | + +### `cloud_environments` Options: + +| Field | Type | Allowed Values | Description | +| ------------ | ------ | ------------------------------ | ----------------------------------- | +| `name` | string | e.g., `eu_de`, `swiss` | Name of the cloud region. | +| `visibility` | string | `public`, `internal`, `hidden` | Controls visibility of the service. | + +### `teams` Options: + +| Field | Type | Allowed Values | Description | +| ------------ | ------ | --------------- | ---------------------------------------- | +| `name` | string | team identifier | Name of the team (e.g., `docs-compute-rw`). | +| `permission` | string | `read`, `write` | Access level to the metadata. |