From 5feae4b748cc668b841f1cd8c7387e6014310e71 Mon Sep 17 00:00:00 2001 From: Steve Goodman <39279277+stoobie@users.noreply.github.com> Date: Tue, 30 Nov 2021 14:56:10 +0200 Subject: [PATCH] FCCEUD-79 Updates to pantheon2.yml file configuration descriptions (#630) * fcceud-79 updates to pantheon2.yml file configuration descriptions * fcceud-79 updates following tech review * variants definitionand example * fcceud-79 updates following review input and suggestions * emarcusRH-fcceud-79 Various clarifications and other edits. Co-authored-by: emarcusRH --- .../docs/modules/con_pantheon_yaml_file.adoc | 58 +++++++++++++++---- 1 file changed, 47 insertions(+), 11 deletions(-) diff --git a/pantheon-bundle/src/main/resources/SLING-INF/content/docs/modules/con_pantheon_yaml_file.adoc b/pantheon-bundle/src/main/resources/SLING-INF/content/docs/modules/con_pantheon_yaml_file.adoc index d710d43e3..af22a758d 100644 --- a/pantheon-bundle/src/main/resources/SLING-INF/content/docs/modules/con_pantheon_yaml_file.adoc +++ b/pantheon-bundle/src/main/resources/SLING-INF/content/docs/modules/con_pantheon_yaml_file.adoc @@ -5,9 +5,8 @@ The configuration file, named `pantheon2.yml`, resides in the root directory of your documentation repository. You use this file to designate a Git repository as a source that {ProductShortName} can use to import content. This configuration file provides the information necessary for {ProductShortName} to interact with files in the repository. //// -// Keeping this section because the status of the Uploader tool is not clear. It might be relevant in the future. +Keeping this section because the status of the Uploader tool is not clear. It might be relevant in the future. The configuration file enables you to perform the following actions: - * Import content from a Git repository into {ProductShortName} * Upload {ContentTerm} into {ProductShortName} using the Uploader tool //// @@ -16,18 +15,55 @@ The configuration file enables you to import content from a Git repository into The {ProductShortName} configuration file defines the following parameters: -* `server` The URL of the {ProductShortName} server. -* `repositories` A multi-valued structure with the following child members: +`server`:: (Required) The URL of the {ProductShortName} server. +`repository`:: (Required) The name of the repository. It is recommended not to include spaces in the repository name. +`variants`:: (Required) Separate sets of output built on the same set of files and differentiated by these values: `name`, `path`, and `canonical`. Modules and assemblies can have variants to differentiate how they are used, and what output is created. + -** `name` (optional) A unique ID that displays in URLs on the {ProductShortName} site when you view modules and assemblies. +** `name` (Optional) A unique ID that is displayed in URLs on the {ProductShortName} site when you view modules and assemblies. If no value is provided for `name`, this field is defined as *DEFAULT*. + For example, if you specify `name: rhel_docs`, and one of your files is named [filename]`foo.adoc`, the module's URL in {ProductShortName} is: -`\http://<_{ProductShortName}__url>/content/repositories/**rhel_docs**/entities/modules/getting_started/foo.adoc.preview` -** `modules` (optional) Patterns for modules that show up in the search results on {ProductShortName}. -** `resources` (optional) Image files, legal information, or other content that is not a complete module or assembly. -** `attributes` (optional) A path to the repository-wide attributes file. Provide this value if your documents relies on the attributes file. -+ -NOTE: You must define the values for `server` and `repository`. +`\https://<_{ProductShortName}__url>/content/repositories/*repository*/entities/modules/getting_started/foo.adoc.preview` +** `path` (Optional) The path containing resource files, such as `attributes.adoc`. +** `canonical` (Required) The primary variant of content. If a search engine sees multiple variants of the same piece of content (HTML page or a group of pages) it needs to know what the primary or original one is to establish ranking. Declaring a piece of content as `canonical` tells the search engine to treat that piece of content as the canonical variant. The canonical declaration is transformed into HTML meta data. Possible values: `*true*` or `*false*`. + +`assemblies`:: (optional) The path to assemblies in the repository that should be uploaded. The path can include specific files or a pattern, such as `*.adoc` to include only `.adoc` files, or `**` to include all files. +`modules`:: Path to modules in the repository that should be uploaded. +`resources`:: (optional) Attributes, image files, snippets, legal information, or other content that is not a complete module or assembly. + +[NOTE] +==== +File paths can indicate specific files, or file patterns. For example: + +* This will upload everything inside `assemblies/`: `assemblies/**` +* This will only upload `.adoc` files inside `assemblies/`: `assemblies/*.adoc` +==== + +.Examples of variants: + +** Document level - _Installing RHV using the command line_; _Installing RHV using the Administration Portal_. +** Module level - The same module is published in multiple Red Hat documents, such as _Red Hat Decision Manager_, _Red Hat Process Automation Manager_. + +.Example YAML file with multiple variants +[source,yaml,options="nowrap",subs="attributes+,+quotes"] +---- +server: https://pantheon.corp.redhat.com +repository: rhel-docs +variants: + - name: rhel9 + path: rhel-9/common-content/attributes.adoc + canonical: true + - name: rhel8 + path: rhel-8/common-content/attributes.adoc + canonical: false +assemblies: + - rhel/assemblies/*.adoc +modules: + - rhel/modules/*.adoc +resources: + - images/*.png +---- + +In the above example, the assemblies and modules for both rhel9 and rhel8 variants are in the same directories, `rhel/assemblies/` and `rhel/modules/`. Depending on the value of their attributes, {ProductShortName} creates the separate variants. .Example {ProductShortName} configuration file [source,yaml,options="nowrap",subs="attributes+,+quotes"]