Merge pull request #645 from inspec/im/readme

Add readme content and configs for documentation

.expeditor/config.yml

@@ -39,12 +39,3 @@ subscriptions:
          ignore_labels:
           - "Changelog: Skip Update"
           - "Expeditor: Skip All"
-  # These actions are taken when `/expeditor promote` is run from Slack
-  # Creates a release by announcing changes since the last announcement
-  # THE SLACK COMMAND IS `expeditor promote inspec-azure`
-  - workload: project_promoted:{{agent_id}}:*
-    actions:
-    - bash:.expeditor/publish-release-notes.sh:
-        post_commit: true
-    - bash:.expeditor/announce-release.sh:
-        post_commit: true

docs-chef-io/.gitignore

@@ -0,0 +1,5 @@
+*.*~
+*~
+
+chef-web-docs/
+.hugo_build.lock

docs-chef-io/Makefile

@@ -0,0 +1,39 @@
+# we use pushd/popd here, and /bin/sh of our chefes/buildkite image is not bash
+# so we have to override the default shell here
+SHELL=bash
+
+preview_netlify: chef_web_docs
+	cp -R content/inspec/resources/* chef-web-docs/_vendor/github.com/inspec/inspec-azure/docs-chef-io/content/inspec/resources/
+	cp -R config.toml chef-web-docs/_vendor/github.com/inspec/inspec-azure/docs-chef-io/
+	pushd chef-web-docs && make assets; hugo --gc --minify --buildFuture && popd
+
+
+replace = "replacements = \'github.com/inspec/inspec-azure/docs-chef-io -\> ../../\'\\n\\n"
+
+serve: chef_web_docs
+	@echo -e "$(replace)" > temp.txt
+	@cat chef-web-docs/config/_default/module.toml >> temp.txt
+	@cat temp.txt > chef-web-docs/config/_default/module.toml
+	rm temp.txt
+	pushd chef-web-docs && make assets; hugo server --buildDrafts --buildFuture --noHTTPCache && popd
+
+chef_web_docs:
+	if [ -d "chef-web-docs/" ]; then \
+		pushd chef-web-docs && git reset HEAD --hard; git clean -fd; git pull --ff-only origin main; rm -rf public && popd; \
+	else \
+		git clone https://github.com/chef/chef-web-docs.git; \
+	fi
+
+clean_all:
+	rm -rf chef-web-docs
+
+clean:
+	pushd chef-web-docs && make clean_all && popd
+
+lint:
+	hugo -D
+
+
+publish_release_notes:
+	$(shell . tools/release-notes/publish-release-notes.sh)
+

docs-chef-io/README.md

@@ -0,0 +1,166 @@
+# Chef InSpec Azure Resource Documentation
+
+This is the home of the InSpec Azure resource documentation found on
+<https://docs.chef.io/inspec/resources/#azure>.
+
+We use [Hugo](https://gohugo.io/) to incorporate documentation from this repository into `chef/chef-web-docs` and deploy it on <https://docs.chef.io>.
+
+## Documentation Content
+
+### Resource Pages
+
+All resource pages are located in `docs-chef-io/content/inspec/resources/`.
+
+Create a new page by duplicating an old page and then update the new page with content relevant to the new resource.
+
+You can also run `hugo new -k resource inspec/resources/RESOURCE_NAME.md` to generate a new resource page from scratch.
+
+See our [style guide](https://docs.chef.io/style_index/) for suggestions on writing documentation.
+
+#### Front Matter
+
+At the top of each resource is a block of front matter, which Hugo uses to add a title to each page and locate each page in the left navigation menu in <docs.chef.io>. Below is an example of a page's front matter:
+
+```toml
++++
+title = "RESOURCE NAME resource"
+platform = "azure"
+gh_repo = "inspec-azure"
+
+[menu.inspec]
+title = "RESOURCE NAME"
+identifier = "inspec/resources/azure/RESOURCE NAME"
+parent = "inspec/resources/azure"
++++
+```
+
+`title` is the page title.
+
+`platform = azure` sorts each page into the correct category in the [Chef InSpec resources list page](https://docs.chef.io/inspec/resources/).
+
+`gh_repo = "inspec-azure"` adds an "[edit on GitHub]" link to the top of each page that links to the Markdown page in the inspec/inspec-azure repository.
+
+`[menu.inspec]` places the page in the Chef InSpec section of the left navigation menu in <docs.chef.io>. All the parameters following this configure the link in the left navigation menu to the page.
+
+`title` is the title of page in the Chef InSpec menu.
+
+`identifier` is the identifier for a page in the menu. It should formatted like this: `inspec/resources/azure/resource name`.
+
+`parent = "inspec/resources/azure"` is the identifier for the section of the menu that the page will be found in. This value is set in the [chef-web-docs menu config](https://github.com/chef/chef-web-docs/blob/main/config/_default/menu.toml).
+
+### Shortcodes
+
+A shortcode is a file with a block of text that can be added in multiple places in our documentation by referencing the shortcode file name.
+
+This documentation set has three shortcodes located in the `docs-chef-io/layouts/shortcodes` directory:
+
+- azure_permissions_service_principal.md
+- inspec_azure_common_parameters.md
+- inspec_azure_install.md
+
+Add a shortcode to a resource page by wrapping the filename, without the `.md` file suffix, in double curly braces and percent symbols. For example: `{{% inspec_azure_install %}}`.
+
+The `azure_permissions_service_principal.md` shortcode requires a `role` parameter, which is the role that the service principal must have for the subscription that will be tested. For example, the azure_redis_cache Resource page has:
+
+```md
+{{% azure_permissions_service_principal role="contributor" %}}
+```
+
+which will render the following text:
+
+> Your [Service Principal](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal) must be set up with at least a `contributor` role on the subscription you wish to test.
+
+**Note:** You can add shortcodes from other repositories. For example, the `inspec_filter_table.md` and the `inspec_matchers_link.md` shortcodes are both located in the chef/chef-web-docs repository, but they can be added to this documentation set using the same method described above.
+
+### Release Dates
+
+The chef/chef-web-docs repository uses the `release-dates.json` file in `docs-chef-io/assets/release-notes/inspec-azure` to generate release notes on <https://docs.chef.io/release_notes_inspec_azure/>. See below for more information on release notes for inspec-azure.
+
+## Update the InSpec Repository Module In `chef/chef-web-docs`
+
+We use [Hugo modules](https://gohugo.io/hugo-modules/) to build Chef's documentation
+from multiple repositories.
+
+When release notes are announced for inspec-azure, the documentation for inspec-azure is updated at the same time. See the section below on release notes.
+
+A member of the Docs Team can also update the inspec-azure resource documentation at any time when new resources are ready to be added to <docs.chef.io>.
+
+## Local Development Environment
+
+We use [Hugo](https://gohugo.io/), [Go](https://golang.org/), and[NPM](https://www.npmjs.com/)
+to build the Chef Documentation website. You will need Hugo 0.93.1 or higher
+installed and running to build and view our documentation.
+
+To install Hugo, NPM, and Go on Windows and macOS:
+
+- On macOS run: `brew install hugo node go`
+- On Windows run: `choco install hugo nodejs golang -y`
+
+To install Hugo on Linux, run:
+
+- `apt install -y build-essential`
+- `snap install node --classic --channel=12`
+- `snap install hugo --channel=extended`
+
+## Preview InSpec Azure Resource Documentation
+
+### make serve
+
+Run `make serve` to build a local preview of the InSpec Azure resource documentation.
+This will clone a copy of `chef/chef-web-docs` into the `docs-chef-io` directory.
+That copy will be configured to build the InSpec Azure resource documentation from the `docs-chef-io` directory
+and live reload if any changes are made while the Hugo server is running.
+
+- Run `make serve`
+- go to <http://localhost:1313/inspec/resources/#azure>
+
+### Clean Your Local Environment
+
+Run `make clean_all` to delete the cloned copy of chef/chef-web-docs.
+
+## Publish Release Notes
+
+The process for publishing and announcing release notes for inspec-azure is mostly manual.
+
+### Edit Pending Release Notes
+
+Edit the Pending Release Notes file in the [inspec-azure wiki](https://github.com/inspec/inspec-azure/wiki/Pending-Release-Notes).
+
+We recommend editing this page as new resources are added or changes are made to the inspec-azure resources.
+
+Have a member of the documentation team review the Pending Release Notes file before they're released.
+
+### Release the Release Notes
+
+1. Log in to the chef-cd S3 account using saml2aws.
+
+2. Run the `publish-release-notes.sh` script in `tools/release-notes`. You can run this from the Makefile with `make publish_release_notes`
+
+   This will push the pending release notes to the S3 chef-cd bucket, reset the Pending Release Notes file, and update the `release-dates.json` file in `assets/release-notes/inspec-azure`.
+
+3. Push up and merge a branch to `inspec/inspec-azure` with the changes made to the `release-dates.json` file.
+
+### chef-web-docs
+
+chef-web-docs is configured to open a PR that will update the inspec-azure content on <doc.chef.io> when a change is committed to the `release-dates.json` file in the inspec-azure repository. This will update the InSpec Azure resource documentation and update release notes for InSpec Azure resources.
+
+A member fo the documentation team can merge that PR for you as soon as it's made.
+
+### Chef Discourse
+
+Copy the release notes to a new announcement in [Chef Release Announcements](https://discourse.chef.io/c/chef-release/9) on Discourse.
+
+You can find the proper release notes in the Pending Release Notes file history or on <https://packages.chef.io/release-notes/inspec-azure/RELEASE_DATE.md>
+
+## Documentation Feedback
+
+If you need support, contact [Chef Support](https://www.chef.io/support/).
+
+**GitHub issues**
+
+Submit an issue to the [inspec-azure repo](https://github.com/inspec/inspec-azure/issues)
+for "important" documentation bugs that may need visibility among a larger group,
+especially in situations where a documentation bug may also surface a product bug.
+
+Submit an issue to [chef-web-docs](https://github.com/chef/chef-web-docs/issues) for
+documentation feature requests and minor documentation issues.

docs-chef-io/archetypes/resource.md

@@ -1,27 +1,73 @@
 +++
-title = "{{ .Name | humanize | title }} resource"
+title = "{{ .Name }} resource"
 draft = false
 gh_repo = "inspec"
 platform = "azure"
 
 [menu]
   [menu.inspec]
-    title = "{{ .Name | humanize | title }}"
-    identifier = "inspec/resources/azure/{{ .Name | humanize | title }}"
+    title = "{{ .Name }}"
+    identifier = "inspec/resources/azure/{{ .Name }}"
     parent = "inspec/resources/azure"
 +++
+{{/* Run `hugo new -k resource inspec/resources/RESOURCE_NAME.md` to generate a new resource page. */}}
 
+Use the `{{ .Name }}` Chef InSpec audit resource to test properties of...
 
-{{% Run `hugo new -k resource resources/RESOURCE_NAME.md` to generate a new resource page. %}}
+## Azure REST API Version, Endpoint, and HTTP Client Parameters
+
+{{% inspec_azure_common_parameters %}}
+
+## Installation
+
+{{% inspec_azure_install %}}
 
 ## Syntax
 
+```ruby
+describe {{ .Name }} do
+
+end
+```
+
 ## Parameters
 
+`PARAMETER` _(required)_
+: PARAMETER DESCRIPTION
+
+`PARAMETER` _(optional)_
+: PARAMETER DESCRIPTION
+
 ## Properties
 
+`PROPERTY`
+: PROPERTY DESCRIPTION
+
+`PROPERTY`
+: PROPERTY DESCRIPTION
+
 ## Examples
 
+**EXAMPLE DESCRIPTION**
+
+```ruby
+describe {{ .Name }} do
+
+end
+```
+
+**EXAMPLE DESCRIPTION**
+
+```ruby
+describe {{ .Name }} do
+
+end
+```
+
 ## Matchers
 
-For a full list of available matchers, please visit our [Universal Matchers page](https://docs.chef.io/inspec/matchers/).
+{{% inspec_matchers_link %}}
+
+## Azure Permissions
+
+{{% azure_permissions_service_principal role="ROLE" %}}

docs-chef-io/content/inspec/resources/azure_active_directory_domain_service.md

@@ -95,7 +95,7 @@ end
 
 ## Matchers
 
-This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+{{% inspec_matchers_link %}}
 
 ### exists
 

docs-chef-io/content/inspec/resources/azure_active_directory_domain_services.md

@@ -140,7 +140,7 @@ end
 
 ## Matchers
 
-This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+{{% inspec_matchers_link %}}
 
 ### exists
 

docs-chef-io/content/inspec/resources/azure_active_directory_object.md

@@ -155,7 +155,7 @@ end
 
 ## Matchers
 
-This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+{{% inspec_matchers_link %}}
 
 ### exists
 

docs-chef-io/content/inspec/resources/azure_active_directory_objects.md

@@ -58,7 +58,7 @@ This resource does not require any parameters.
 
 ## Matchers
 
-This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+{{% inspec_matchers_link %}}
 
 ### exists
 

docs-chef-io/content/inspec/resources/azure_aks_cluster.md

@@ -90,20 +90,23 @@ azure_aks_clusters.ids.each do |resource_id|
   end
 end 
 ```
+
 **Test that a Specified AKS Cluster has the Correct Number of Nodes in Pool.**
 
 ```ruby
 describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
   its('properties.agentPoolProfiles.first.count') { should cmp 5 }
 end
 ```
+
 **Test that a Specified AKS Cluster has kube-audit logging enabled.**
 
 ```ruby
 describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
   its('enabled_logging_types') { should include "kube-audit" }
 end
 ```
+
 **Test that a Specified AKS Cluster has logging enabled on it and no forms of logging disabled.**
 
 ```ruby