creating md files for hld commands (#332)

dennisseah · web-flow · commit 66c8460138a0 · 2020-02-24T14:46:07.000-08:00
diff --git a/guides/hld-management.md b/guides/hld-management.md
@@ -3,28 +3,6 @@
 Initialize a Bedrock HLD (High Level Definition) repository and deploy pipelines
 to materalize manifests.
 
-Usage:
-
-```
-spk hld [command] [options]
-```
-
-Commands:
-
-- [HLD - High Level Definition](#hld---high-level-definition)
-  - [Requirements](#requirements)
-  - [Commands](#commands)
-    - [init](#init)
-    - [install-manifest-pipeline](#install-manifest-pipeline)
-    - [reconcile](#reconcile)
-
-Global options:
-
-```
-  -v, --verbose        Enable verbose logging
-  -h, --help           Usage information
-```
-
 ## Requirements
 
 There are a few base assumptions that `spk` makes, as this will affect the set
@@ -49,190 +27,22 @@ azure_devops:
   project: "fabrikam" # Your AzDo project
 ```
 
-## Commands
-
-### init
-
-Initialize the HLD repository by creating the pipeline
-`manifest-generation.yaml` file, and the default `component.yaml` for
-[fabrikate](https://github.com/microsoft/fabrikate) to consume, if each does not
-already exist.
+## Usage
 
 ```
-Usage: hld init|i [options]
-
-Initialize High Level Definition repository. Add manifest-generation.yaml file to working directory/repository if it does not already exist.
-
-Options:
-  --git-push                                          SPK CLI will try to commit and push these changes to a new origin/branch. (default: false)
-  --default-component-git <component-repository-url>  The default hld repository's component's git repository url. (default: "https://github.com/microsoft/fabrikate-definitions.git")
-  --default-component-name <component-name>           The default hld repository's component's name. (default: "traefik2")
-  --default-component-path <component-path>           The default hld repository's component's path. (default: "definitions/traefik2")
-  -h, --help                                          output usage information
-
-```
-
-The created `component.yaml` will be populated with a traefik2 definition by
-default:
-
-```
-name: default-component
-subcomponents:
-  - name: traefik2
-    method: git
-    source: 'https://github.com/microsoft/fabrikate-definitions.git'
-    path: definitions/traefik2
-```
-
-However, you can set a another fabrikate definition to be added instead via the
-`--default-component-*` flags.
-
-### install-manifest-pipeline
-
-After merging the azure-pipelines yaml file generated by the init step above
-into the `master` branch, run the following command to install the HLD to
-Manifest pipeline. This pipeline will be triggered on commits to master and
-invoke "manifest generation"
-[(via fabrikate)](https://github.com/microsoft/fabrikate), rendering helm charts
-and configuration into Kubernetes yaml.
-
-```
-Usage: hld install-manifest-pipeline|p [options]
-
-Install the manifest generation pipeline to your Azure DevOps instance. Default values are set in spk-config.yaml and can be loaded via spk init or overriden via option flags.
-
-Options:
-  -n, --pipeline-name <pipeline-name>                  Name of the pipeline to be created (default: "")
-  -p, --personal-access-token <personal-access-token>  Personal Access Token (default: "")
-  -o, --org-name <org-name>                            Organization Name for Azure DevOps (default: "")
-  -u, --hld-url <hld-url>                              HLD Repository URL (default: "")
-  -m, --manifest-url <manifest-url>                    Manifest Repository URL (default: "")
-  -d, --devops-project <devops-project>                Azure DevOps Project (default: "")
-  -b, --build-script-url <build-script-url>            Build Script URL. By default it is 'https://raw.githubusercontent.com/Microsoft/bedrock/master/gitops/azure-devops/build.sh'. (default: "https://raw.githubusercontent.com/Microsoft/bedrock/master/gitops/azure-devops/build.sh")
-  --yaml-file-branch <yaml-file-branch>                The git branch where the pipeline definition yaml file is located. (default: "master")
-  -h, --help                                           output usage information
-```
-
-### reconcile
-
-The reconcile feature scaffolds a HLD with the services in the `bedrock.yaml`
-file at the root level of the application repository. Recall that in a
-mono-repo, `spk service create` will add an entry into the `bedrock.yaml`
-corresponding to all tracked services. When the service has been merged into
-`master` of the application repository, a pipeline (see `hld-lifecycle.yaml`,
-created by `spk project init`) runs `spk hld reconcile` to add any _new_
-services tracked in `bedrock.yaml` to the HLD.
-
-This command is _intended_ to be run in a pipeline (see the generated
-`hld-lifecycle.yaml` created from `spk project init`), but can be run by the
-user in a CLI for verification.
-
-```
-Usage: hld reconcile|r [options] <repository-name> <hld-path> <bedrock-application-repo-path>
-
-Reconcile a HLD with the services tracked in bedrock.yaml.
-
-Options:
-  -h, --help  output usage information
-```
-
-For a `bedrock.yaml` file that contained within the
-`https://dev.azure.com/foo/bar/_git` repository, that has the following
-structure:
-
-```
-rings:
-  master:
-    isDefault: true
-services:
-  ./services/fabrikam:
-    displayName: 'fabrikam'
-    k8sBackendPort: 8001
-    k8sBackend: 'fabrikam-k8s-svc'
-    pathPrefix: 'fabrikam-service'
-    pathPrefixMajorVersion: 'v1'
-    helm:
-      chart:
-        branch: master
-        git: 'https://dev.azure.com/foo/bar/_git'
-        path: stable/fabrikam-application
-    middlewares:
-      - ''
-variableGroups:
-  - fabrikam-vg
-```
-
-A HLD is produced that resembles the following:
-
-```
-├── component.yaml
-└── fabrikam
-    ├── access.yaml
-    ├── component.yaml
-    ├── config
-    │   └── common.yaml
-    └── fabrikam
-        ├── component.yaml
-        ├── config
-        │   └── common.yaml
-        └── master
-            ├── component.yaml
-            ├── config
-            │   └── common.yaml
-            └── static
-                ├── ingress-route.yaml
-                └── middlewares.yaml
-```
-
-With the `ingress-route.yaml` representing a
-[Traefik2 Ingress Route](https://docs.traefik.io/routing/providers/kubernetes-crd/#kind-ingressroute)
-backed by a Kubernetes Service, and the `middlewares.yaml` representing a
-[Traefik2 Middleware](https://docs.traefik.io/routing/providers/kubernetes-crd/#kind-middleware)
-that strips path prefixes.
-
-For the `bedrock.yaml` shown above, the `ingress-route.yaml` produced is:
-
-```
-apiVersion: traefik.containo.us/v1alpha1
-kind: IngressRoute
-metadata:
-  name: fabrikam-master
-spec:
-  routes:
-    - kind: Rule
-      match: 'PathPrefix(`/v1/fabrikam-service`) && Headers(`Ring`, `master`)'
-      middlewares:
-        - name: fabrikam-master
-      services:
-        - name: fabrikam-k8s-svc-master
-          port: 8001
+spk hld [command] [options]
 ```
 
-And the `middlewares.yaml` produced is:
+## Commands:
 
-```
-apiVersion: traefik.containo.us/v1alpha1
-kind: Middleware
-metadata:
-  name: fabrikam-master
-spec:
-  stripPrefix:
-    forceSlash: false
-    prefixes:
-      - /v1/fabrikam-service
-```
+- [init](https://catalystcode.github.io/spk/commands/index.html#hld_init)
+- [install-manifest-pipeline](https://catalystcode.github.io/spk/commands/index.html#hld_install-manifest-pipeline)
+- [reconcile](https://catalystcode.github.io/spk/commands/index.html#hld_reconcile)
 
-Note that there exists a third generated file, `access.yaml`. For the above
-`bedrock.yaml`, `access.yaml` contains a single line, which represents a
-[Fabrikate access.yaml definition](https://github.com/microsoft/fabrikate/blob/master/docs/auth.md#accessyaml),
-allowing Fabrikate to pull Helm Charts that are contained within the same
-application repository:
+## Global options:
 
 ```
-'https://dev.azure.com/foo/bar/_git': ACCESS_TOKEN_SECRET
+  -V, --version        output the version number
+  -v, --verbose        Enable verbose logging
+  -h, --help           Usage information
 ```
-
-When `fabrikate` is invoked in the HLD to Manifest pipeline, it will utilize the
-`ACCESS_TOKEN_SECRET` environment variable injected at pipeline run-time as a
-Personal Access Token to pull any referenced helm charts from the application
-repository.
diff --git a/guides/project-management.md b/guides/project-management.md
@@ -3,27 +3,18 @@
 Create and manage components for a Bedrock project. All project management
 commands will need to run in the order as listed below due to dependencies.
 
-Usage:
+## Prerequisites
+
+An Azure DevOps git repository.
+
+## Usage
 
 ```
 Usage: project [options] [command]
 
 Initialize and manage your Bedrock project.
-
-Options:
-  -v, --verbose                                              Enable verbose logging
-  -h, --help                                                 output usage information
-
-Commands:
-  create-variable-group|cvg [options] <variable-group-name>  Create a new variable group in Azure DevOps project with specific variables (ACR name, HLD Repo name, Personal Access Token, Service Principal id, Service Principal password, and Azure AD tenant id)
-  init|i [options]                                           Initialize your spk repository. Add starter bedrock.yaml, maintainers.yaml, hld-lifecycle.yaml, and .gitignore files to your project.
-  install-lifecycle-pipeline|p [options]                     Install the hld lifecycle pipeline to your Azure DevOps instance
 ```
 
-## Prerequisites
-
-An Azure DevOps git repository.
-
 ## Commands
 
 - [init](https://catalystcode.github.io/spk/commands/index.html#project_init)
@@ -32,3 +23,12 @@ An Azure DevOps git repository.
 
 **Please note all project management commands must run in the order as listed
 above.**
+
+## Global Options
+
+```
+  -V, --version        output the version number
+  -v, --verbose        Enable verbose logging
+  -h, --help           output usage information
+
+```
diff --git a/guides/service-management.md b/guides/service-management.md
@@ -11,15 +11,16 @@ Usage:
 spk service [command] [options]
 ```
 
-Commands:
+## Commands
 
 - [create](https://catalystcode.github.io/spk/commands/index.html#service_create)
 - [install-build-pipeline](https://catalystcode.github.io/spk/commands/index.html#service_install-build-pipeline)
 - [create-revision](https://catalystcode.github.io/spk/commands/index.html#service_create-revision)
 
-Global options:
+## Global options
 
 ```
+  -V, --version        output the version number
   -v, --verbose        Enable verbose logging
   -h, --help           Usage information
 ```
diff --git a/src/commands/hld/init.md b/src/commands/hld/init.md
@@ -0,0 +1,21 @@
+## Description
+
+Initializes the HLD repository by creating the pipeline
+`manifest-generation.yaml` file, and the default `component.yaml` for
+[fabrikate](https://github.com/microsoft/fabrikate) to consume, if each does not
+already exist.
+
+The created `component.yaml` will be populated with a traefik2 definition by
+default:
+
+```
+name: default-component
+subcomponents:
+  - name: traefik2
+    method: git
+    source: 'https://github.com/microsoft/fabrikate-definitions.git'
+    path: definitions/traefik2
+```
+
+However, you can set a another fabrikate definition to be added instead via the
+`--default-component-*` flags.
diff --git a/src/commands/hld/pipeline.md b/src/commands/hld/pipeline.md
@@ -0,0 +1,8 @@
+## Description
+
+After merging the azure-pipelines yaml file generated by the init step above
+into the `master` branch, run the following command to install the HLD to
+Manifest pipeline. This pipeline will be triggered on commits to master and
+invoke "manifest generation"
+[(via fabrikate)](https://github.com/microsoft/fabrikate), rendering helm charts
+and configuration into Kubernetes yaml.
diff --git a/src/commands/hld/reconcile.md b/src/commands/hld/reconcile.md
