Explanation on airship config file

This fix closes issue #74 of treasuremap https://github.com/airshipit/treasuremap/issues/74

Closes: #74
Change-Id: I439db7270ecad17435f18b8eb5f8906d7c0325de

cmd/config/set_manifest.go

@@ -28,7 +28,8 @@ const (
 Creates or modifies a manifests in the airshipctl config file based on the MANIFEST_NAME argument passed.
 The optional flags that can be passed to the command are repo name, url, branch name, tag name, commit hash,
 target-path and metadata-path. Use --force flag to enable force checkout of the repo. And use --phase flag
-to enable phase repository.
+to enable phase repository. For any new site deployment, or testing of any new function or composite, this
+config file will not have any customization, respective changes need to be done in the manifest files only.
 `
 
 	setManifestsExample = `

cmd/config/testdata/TestConfigSetManifestGoldenOutput/config-cmd-set-manifest-with-help.golden

@@ -1,7 +1,8 @@
 Creates or modifies a manifests in the airshipctl config file based on the MANIFEST_NAME argument passed.
 The optional flags that can be passed to the command are repo name, url, branch name, tag name, commit hash,
 target-path and metadata-path. Use --force flag to enable force checkout of the repo. And use --phase flag
-to enable phase repository.
+to enable phase repository. For any new site deployment, or testing of any new function or composite, this
+config file will not have any customization, respective changes need to be done in the manifest files only.
 
 Usage:
   set-manifest MANIFEST_NAME [flags]

cmd/document/pull.go

@@ -37,7 +37,71 @@ manifests and with the manifests target path "%s".
 	pullExample = `
 Pull manifests from remote repos
 # airshipctl document pull
->>>>>>> Updating cmd files for documentation
+For the below sample airship config file, it will pull from remote repository where URL mentioned
+to the target location /home/airship with manifests->treasuremap->repositories->airshipctl->checkout
+options branch, commitHash & tag mentioned in manifest section.
+In the URL section, instead of a remote repository location we can also mention already checkout directory,
+in this case we need not use document pull otherwise, any temporary changes will be overwritten.
+>>>>>>Sample Config File<<<<<<<<<
+cat ~/.airship/config
+apiVersion: airshipit.org/v1alpha1
+contexts:
+  ephemeral-cluster:
+    managementConfiguration: treasuremap_config
+    manifest: treasuremap
+  target-cluster:
+    managementConfiguration: treasuremap_config
+    manifest: treasuremap
+currentContext: ephemeral-cluster
+kind: Config
+managementConfiguration:
+  treasuremap_config:
+    insecure: true
+    systemActionRetries: 30
+    systemRebootDelay: 30
+    type: redfish
+manifests:
+  treasuremap:
+    inventoryRepositoryName: primary
+    metadataPath: manifests/site/eric-test-site/metadata.yaml
+    phaseRepositoryName: primary
+    repositories:
+      airshipctl:
+        checkout:
+          branch: ""
+          commitHash: f4cb1c44e0283c38a8bc1be5b8d71020b5d30dfb
+          force: false
+          localBranch: false
+          tag: ""
+        url: https://opendev.org/airship/airshipctl.git
+      primary:
+        checkout:
+          branch: ""
+          commitHash: 5556edbd386191de6c1ba90757d640c1c63c6339
+          force: false
+          localBranch: false
+          tag: ""
+        url: https://opendev.org/airship/treasuremap.git
+    targetPath: /home/airship
+permissions:
+  DirectoryPermission: 488
+  FilePermission: 416
+>>>>>>>>Sample output of document pull for above configuration<<<<<<<<<
+pkg/document/pull/pull.go:36: Reading current context manifest information from /home/airship/.airship/config
+(currentContext:)
+pkg/document/pull/pull.go:51: Downloading airshipctl repository airshipctl from https://opendev.org/airship/
+airshipctl.git into /home/airship (url: & targetPath:)
+pkg/document/repo/repo.go:141: Attempting to download the repository airshipctl
+pkg/document/repo/repo.go:126: Attempting to clone the repository airshipctl from https://opendev.org/airship/
+airshipctl.git
+pkg/document/repo/repo.go:120: Attempting to open repository airshipctl
+pkg/document/repo/repo.go:110: Attempting to checkout the repository airshipctl from commit hash #####
+pkg/document/pull/pull.go:51: Downloading primary repository treasuremap from https://opendev.org/airship/
+treasuremap.git into /home/airship  (repository name taken from url path last content)
+pkg/document/repo/repo.go:141: Attempting to download the repository treasuremap
+pkg/document/repo/repo.go:126: Attempting to clone the repository treasuremap from /home/airship/treasuremap
+pkg/document/repo/repo.go:120: Attempting to open repository treasuremap
+pkg/document/repo/repo.go:110: Attempting to checkout the repository treasuremap from commit hash #####
 `
 )
 

cmd/document/testdata/TestPullGoldenOutput/document-pull-cmd-with-help.golden

@@ -12,7 +12,71 @@ Examples:
 
 Pull manifests from remote repos
 # airshipctl document pull
->>>>>>> Updating cmd files for documentation
+For the below sample airship config file, it will pull from remote repository where URL mentioned
+to the target location /home/airship with manifests->treasuremap->repositories->airshipctl->checkout
+options branch, commitHash & tag mentioned in manifest section.
+In the URL section, instead of a remote repository location we can also mention already checkout directory,
+in this case we need not use document pull otherwise, any temporary changes will be overwritten.
+>>>>>>Sample Config File<<<<<<<<<
+cat ~/.airship/config
+apiVersion: airshipit.org/v1alpha1
+contexts:
+  ephemeral-cluster:
+    managementConfiguration: treasuremap_config
+    manifest: treasuremap
+  target-cluster:
+    managementConfiguration: treasuremap_config
+    manifest: treasuremap
+currentContext: ephemeral-cluster
+kind: Config
+managementConfiguration:
+  treasuremap_config:
+    insecure: true
+    systemActionRetries: 30
+    systemRebootDelay: 30
+    type: redfish
+manifests:
+  treasuremap:
+    inventoryRepositoryName: primary
+    metadataPath: manifests/site/eric-test-site/metadata.yaml
+    phaseRepositoryName: primary
+    repositories:
+      airshipctl:
+        checkout:
+          branch: ""
+          commitHash: f4cb1c44e0283c38a8bc1be5b8d71020b5d30dfb
+          force: false
+          localBranch: false
+          tag: ""
+        url: https://opendev.org/airship/airshipctl.git
+      primary:
+        checkout:
+          branch: ""
+          commitHash: 5556edbd386191de6c1ba90757d640c1c63c6339
+          force: false
+          localBranch: false
+          tag: ""
+        url: https://opendev.org/airship/treasuremap.git
+    targetPath: /home/airship
+permissions:
+  DirectoryPermission: 488
+  FilePermission: 416
+>>>>>>>>Sample output of document pull for above configuration<<<<<<<<<
+pkg/document/pull/pull.go:36: Reading current context manifest information from /home/airship/.airship/config
+(currentContext:)
+pkg/document/pull/pull.go:51: Downloading airshipctl repository airshipctl from https://opendev.org/airship/
+airshipctl.git into /home/airship (url: & targetPath:)
+pkg/document/repo/repo.go:141: Attempting to download the repository airshipctl
+pkg/document/repo/repo.go:126: Attempting to clone the repository airshipctl from https://opendev.org/airship/
+airshipctl.git
+pkg/document/repo/repo.go:120: Attempting to open repository airshipctl
+pkg/document/repo/repo.go:110: Attempting to checkout the repository airshipctl from commit hash #####
+pkg/document/pull/pull.go:51: Downloading primary repository treasuremap from https://opendev.org/airship/
+treasuremap.git into /home/airship  (repository name taken from url path last content)
+pkg/document/repo/repo.go:141: Attempting to download the repository treasuremap
+pkg/document/repo/repo.go:126: Attempting to clone the repository treasuremap from /home/airship/treasuremap
+pkg/document/repo/repo.go:120: Attempting to open repository treasuremap
+pkg/document/repo/repo.go:110: Attempting to checkout the repository treasuremap from commit hash #####
 
 
 Flags:

docs/source/cli/config/airshipctl_config_set-manifest.rst

@@ -12,7 +12,8 @@ Synopsis
 Creates or modifies a manifests in the airshipctl config file based on the MANIFEST_NAME argument passed.
 The optional flags that can be passed to the command are repo name, url, branch name, tag name, commit hash,
 target-path and metadata-path. Use --force flag to enable force checkout of the repo. And use --phase flag
-to enable phase repository.
+to enable phase repository. For any new site deployment, or testing of any new function or composite, this
+config file will not have any customization, respective changes need to be done in the manifest files only.
 
 
 ::

docs/source/cli/document/airshipctl_document_pull.rst

@@ -29,7 +29,71 @@ Examples
 
   Pull manifests from remote repos
   # airshipctl document pull
-  >>>>>>> Updating cmd files for documentation
+  For the below sample airship config file, it will pull from remote repository where URL mentioned
+  to the target location /home/airship with manifests->treasuremap->repositories->airshipctl->checkout
+  options branch, commitHash & tag mentioned in manifest section.
+  In the URL section, instead of a remote repository location we can also mention already checkout directory,
+  in this case we need not use document pull otherwise, any temporary changes will be overwritten.
+  >>>>>>Sample Config File<<<<<<<<<
+  cat ~/.airship/config
+  apiVersion: airshipit.org/v1alpha1
+  contexts:
+    ephemeral-cluster:
+      managementConfiguration: treasuremap_config
+      manifest: treasuremap
+    target-cluster:
+      managementConfiguration: treasuremap_config
+      manifest: treasuremap
+  currentContext: ephemeral-cluster
+  kind: Config
+  managementConfiguration:
+    treasuremap_config:
+      insecure: true
+      systemActionRetries: 30
+      systemRebootDelay: 30
+      type: redfish
+  manifests:
+    treasuremap:
+      inventoryRepositoryName: primary
+      metadataPath: manifests/site/eric-test-site/metadata.yaml
+      phaseRepositoryName: primary
+      repositories:
+        airshipctl:
+          checkout:
+            branch: ""
+            commitHash: f4cb1c44e0283c38a8bc1be5b8d71020b5d30dfb
+            force: false
+            localBranch: false
+            tag: ""
+          url: https://opendev.org/airship/airshipctl.git
+        primary:
+          checkout:
+            branch: ""
+            commitHash: 5556edbd386191de6c1ba90757d640c1c63c6339
+            force: false
+            localBranch: false
+            tag: ""
+          url: https://opendev.org/airship/treasuremap.git
+      targetPath: /home/airship
+  permissions:
+    DirectoryPermission: 488
+    FilePermission: 416
+  >>>>>>>>Sample output of document pull for above configuration<<<<<<<<<
+  pkg/document/pull/pull.go:36: Reading current context manifest information from /home/airship/.airship/config
+  (currentContext:)
+  pkg/document/pull/pull.go:51: Downloading airshipctl repository airshipctl from https://opendev.org/airship/
+  airshipctl.git into /home/airship (url: & targetPath:)
+  pkg/document/repo/repo.go:141: Attempting to download the repository airshipctl
+  pkg/document/repo/repo.go:126: Attempting to clone the repository airshipctl from https://opendev.org/airship/
+  airshipctl.git
+  pkg/document/repo/repo.go:120: Attempting to open repository airshipctl
+  pkg/document/repo/repo.go:110: Attempting to checkout the repository airshipctl from commit hash #####
+  pkg/document/pull/pull.go:51: Downloading primary repository treasuremap from https://opendev.org/airship/
+  treasuremap.git into /home/airship  (repository name taken from url path last content)
+  pkg/document/repo/repo.go:141: Attempting to download the repository treasuremap
+  pkg/document/repo/repo.go:126: Attempting to clone the repository treasuremap from /home/airship/treasuremap
+  pkg/document/repo/repo.go:120: Attempting to open repository treasuremap
+  pkg/document/repo/repo.go:110: Attempting to checkout the repository treasuremap from commit hash #####
 
 
 Options