From 4287fc4987933ed661722074f039d092d8093509 Mon Sep 17 00:00:00 2001 From: Ian Maddaus Date: Thu, 19 Jan 2023 13:18:57 -0500 Subject: [PATCH] DOC-212 Test out different resource docs layout Signed-off-by: Ian Maddaus --- content/resources/_index.md | 3 +- .../resources/alternatives/data.yaml | 60 +------- content/resources/alternatives/examples.md | 48 +++++++ .../index.md} | 13 +- .../alternatives/resource_description.md | 2 + .../resources/apt_package/data.yaml | 51 +------ content/resources/apt_package/examples.md | 27 ++++ .../{apt_package.md => apt_package/index.md} | 15 +- .../apt_package/resource_description.md | 2 + .../apt_package/syntax_description.md | 8 ++ .../md/notes_resource_based_on_package.md | 6 + .../md/resources_common_actions_nothing.md | 3 + .../layouts/_default/infra_resource_test.html | 135 ++++++++++++++++++ 13 files changed, 260 insertions(+), 113 deletions(-) rename data/infra/resources/alternatives.yaml => content/resources/alternatives/data.yaml (60%) create mode 100644 content/resources/alternatives/examples.md rename content/resources/{alternatives.md => alternatives/index.md} (68%) create mode 100644 content/resources/alternatives/resource_description.md rename data/infra/resources/apt_package.yaml => content/resources/apt_package/data.yaml (73%) create mode 100644 content/resources/apt_package/examples.md rename content/resources/{apt_package.md => apt_package/index.md} (64%) create mode 100644 content/resources/apt_package/resource_description.md create mode 100644 content/resources/apt_package/syntax_description.md create mode 100644 content/reusable/md/notes_resource_based_on_package.md create mode 100644 content/reusable/md/resources_common_actions_nothing.md create mode 100644 themes/docs-new/layouts/_default/infra_resource_test.html diff --git a/content/resources/_index.md b/content/resources/_index.md index b3a8a3a816..7299aa3ae0 100644 --- a/content/resources/_index.md +++ b/content/resources/_index.md @@ -5,8 +5,7 @@ description = "This reference describes each of the resources available to Chef gh_repo = "chef-web-docs" aliases = ["/resource_reference.html", "/resources.html", "resource_examples.html", "/chef/resources.html"] data_path = ["infra","resources"] -layout = "infra_resources_all" -toc_layout = "infra_resources_all_toc" + [cascade] product = ["client"] diff --git a/data/infra/resources/alternatives.yaml b/content/resources/alternatives/data.yaml similarity index 60% rename from data/infra/resources/alternatives.yaml rename to content/resources/alternatives/data.yaml index 46de9b9adc..35a3b568ff 100644 --- a/data/infra/resources/alternatives.yaml +++ b/content/resources/alternatives/data.yaml @@ -1,13 +1,4 @@ --- -resource_reference: true -resources_common_guards: true -resources_common_notification: true -resources_common_properties: true -resource: alternatives -resource_description_list: -- markdown: Use the **alternatives** resource to configure command alternatives in - Linux using the alternatives or update-alternatives packages. -resource_new_in: '16.0' syntax_full_code_block: |- alternatives 'name' do link String # default value: "/usr/bin/LINK_NAME" @@ -26,7 +17,7 @@ syntax_full_properties_list: resource." actions_list: :nothing: - shortcode: resources_common_actions_nothing.md + file: content/reusable/md/resources_common_actions_nothing.md :install: markdown: Install an alternative on the system including symlinks. (default) :set: @@ -62,52 +53,3 @@ properties_list: required: false description_list: - markdown: The priority of the alternative. -examples: | - **Install an alternative**: - - ```ruby - alternatives 'python install 2' do - link_name 'python' - path '/usr/bin/python2.7' - priority 100 - action :install - end - ``` - - **Set an alternative**: - - ```ruby - alternatives 'python set version 3' do - link_name 'python' - path '/usr/bin/python3' - action :set - end - ``` - - **Set the automatic alternative state**: - - ```ruby - alternatives 'python auto' do - link_name 'python' - action :auto - end - ``` - - **Refresh an alternative**: - - ```ruby - alternatives 'python refresh' do - link_name 'python' - action :refresh - end - ``` - - **Remove an alternative**: - - ```ruby - alternatives 'python remove' do - link_name 'python' - path '/usr/bin/python3' - action :remove - end - ``` \ No newline at end of file diff --git a/content/resources/alternatives/examples.md b/content/resources/alternatives/examples.md new file mode 100644 index 0000000000..6aa2e1ede6 --- /dev/null +++ b/content/resources/alternatives/examples.md @@ -0,0 +1,48 @@ +**Install an alternative**: + +```ruby +alternatives 'python install 2' do + link_name 'python' + path '/usr/bin/python2.7' + priority 100 + action :install +end +``` + +**Set an alternative**: + +```ruby +alternatives 'python set version 3' do + link_name 'python' + path '/usr/bin/python3' + action :set +end +``` + +**Set the automatic alternative state**: + +```ruby +alternatives 'python auto' do + link_name 'python' + action :auto +end +``` + +**Refresh an alternative**: + +```ruby +alternatives 'python refresh' do + link_name 'python' + action :refresh +end +``` + +**Remove an alternative**: + +```ruby +alternatives 'python remove' do + link_name 'python' + path '/usr/bin/python3' + action :remove +end +``` diff --git a/content/resources/alternatives.md b/content/resources/alternatives/index.md similarity index 68% rename from content/resources/alternatives.md rename to content/resources/alternatives/index.md index 750210d12e..ab2a3b06d5 100644 --- a/content/resources/alternatives.md +++ b/content/resources/alternatives/index.md @@ -4,8 +4,17 @@ draft = false robots = "" gh_repo = "chef-web-docs" data_path = ["infra","resources","alternatives"] -layout = "infra_resource" -toc_layout = "infra_resource_toc" +layout = "infra_resource_test" + +resource_reference = true +resources_common_guards = true +resources_common_notification = true +resources_common_properties = true +resource = "alternatives" +resource_new_in = '16.0' +resource_description = [ + "content/resources/alternatives/description.md", +] [menu] [menu.infra] diff --git a/content/resources/alternatives/resource_description.md b/content/resources/alternatives/resource_description.md new file mode 100644 index 0000000000..da634146a7 --- /dev/null +++ b/content/resources/alternatives/resource_description.md @@ -0,0 +1,2 @@ +Use the **alternatives** resource to configure command alternatives in +Linux using the alternatives or update-alternatives packages. diff --git a/data/infra/resources/apt_package.yaml b/content/resources/apt_package/data.yaml similarity index 73% rename from data/infra/resources/apt_package.yaml rename to content/resources/apt_package/data.yaml index bd8956a3bd..3eda7744b4 100644 --- a/data/infra/resources/apt_package.yaml +++ b/content/resources/apt_package/data.yaml @@ -1,23 +1,4 @@ --- -resource_reference: true -multi_package_resource: true -resources_common_guards: true -resources_common_notification: true -resources_common_properties: true -resource: apt_package -resource_description_list: -- markdown: Use the **apt_package** resource to manage packages on Debian, Ubuntu, - and other platforms that use the APT package system. -- notes_resource_based_on_package: true -syntax_description: | - An **apt_package** resource block manages a package on a node, - typically by installing it. The simplest use of the **apt_package** resource is: - - ```ruby - apt_package 'package_name' - ``` - - which will install the named package using all of the default options and the default action of `:install`. syntax_full_code_block: |- apt_package 'name' do default_release String @@ -63,6 +44,8 @@ properties_list: required: false description_list: - markdown: 'The default release. For example: `stable`.' + - file: 'content/reusable/md/notes_resource_based_on_package.md' + - markdown: '**TESTING** Additional text for testing. **TESTING** ' - property: options ruby_type: String, Array required: false @@ -107,34 +90,6 @@ properties_list: - markdown: The amount of time (in seconds) to wait before timing out. - property: version ruby_type: String, Array - required: false + required: true description_list: - markdown: The version of a package to be installed or upgraded. -examples: | - **Install a package using package manager**: - - ```ruby - apt_package 'name of package' do - action :install - end - ``` - - **Install a package without specifying the default action**: - - ```ruby - apt_package 'name of package' - ``` - - **Install multiple packages at once**: - - ```ruby - apt_package %w(package1 package2 package3) - ``` - - **Install without using recommend packages as a dependency**: - - ```ruby - package 'apache2' do - options '--no-install-recommends' - end - ``` diff --git a/content/resources/apt_package/examples.md b/content/resources/apt_package/examples.md new file mode 100644 index 0000000000..72bbf2f037 --- /dev/null +++ b/content/resources/apt_package/examples.md @@ -0,0 +1,27 @@ +**Install a package using package manager**: + +```ruby +apt_package 'name of package' do + action :install +end +``` + +**Install a package without specifying the default action**: + +```ruby +apt_package 'name of package' +``` + +**Install multiple packages at once**: + +```ruby +apt_package %w(package1 package2 package3) +``` + +**Install without using recommend packages as a dependency**: + +```ruby +package 'apache2' do + options '--no-install-recommends' +end +``` diff --git a/content/resources/apt_package.md b/content/resources/apt_package/index.md similarity index 64% rename from content/resources/apt_package.md rename to content/resources/apt_package/index.md index 495f6d58d5..5b159fc441 100644 --- a/content/resources/apt_package.md +++ b/content/resources/apt_package/index.md @@ -4,8 +4,19 @@ draft = false robots = "" gh_repo = "chef-web-docs" data_path = ["infra","resources","apt_package"] -layout = "infra_resource" -toc_layout = "infra_resource_toc" +layout = "infra_resource_test" + +resource_reference = true +multi_package_resource = true +resources_common_guards = true +resources_common_notification = true +resources_common_properties = true +resource = "apt_package" + +resource_description = [ + "content/resources/apt_package/description.md", + "content/reusable/md/notes_resource_based_on_package.md" +] [menu] [menu.infra] diff --git a/content/resources/apt_package/resource_description.md b/content/resources/apt_package/resource_description.md new file mode 100644 index 0000000000..b95b4b158d --- /dev/null +++ b/content/resources/apt_package/resource_description.md @@ -0,0 +1,2 @@ +Use the **apt_package** resource to manage packages on Debian, Ubuntu, +and other platforms that use the APT package system. diff --git a/content/resources/apt_package/syntax_description.md b/content/resources/apt_package/syntax_description.md new file mode 100644 index 0000000000..6af583dcea --- /dev/null +++ b/content/resources/apt_package/syntax_description.md @@ -0,0 +1,8 @@ +An **apt_package** resource block manages a package on a node, +typically by installing it. The simplest use of the **apt_package** resource is: + +```ruby +apt_package 'package_name' +``` + +which will install the named package using all of the default options and the default action of `:install`. diff --git a/content/reusable/md/notes_resource_based_on_package.md b/content/reusable/md/notes_resource_based_on_package.md new file mode 100644 index 0000000000..159b9c4f58 --- /dev/null +++ b/content/reusable/md/notes_resource_based_on_package.md @@ -0,0 +1,6 @@ +In many cases, it is better to use the **package** resource instead of +this one. This is because when the **package** resource is used in a +recipe, Chef Infra Client will use details that are collected by Ohai at +the start of a Chef Infra Client run to determine the correct package +application. Using the **package** resource allows a recipe to be +authored in a way that allows it to be used across many platforms. diff --git a/content/reusable/md/resources_common_actions_nothing.md b/content/reusable/md/resources_common_actions_nothing.md new file mode 100644 index 0000000000..403c3a0765 --- /dev/null +++ b/content/reusable/md/resources_common_actions_nothing.md @@ -0,0 +1,3 @@ +This resource block does not act unless notified by another resource to +take action. Once notified, this resource block either runs immediately +or is queued up to run at the end of a Chef Infra Client run. diff --git a/themes/docs-new/layouts/_default/infra_resource_test.html b/themes/docs-new/layouts/_default/infra_resource_test.html new file mode 100644 index 0000000000..2fd8c54f2a --- /dev/null +++ b/themes/docs-new/layouts/_default/infra_resource_test.html @@ -0,0 +1,135 @@ +{{ define "main" }} +{{ $product := index .Params.data_path 0 }} + +
+
+ +

{{ .Title }}

+ + + +
+ {{ if eq $product "infra" }} +

+ +

+

+ This page is generated from the Chef Infra Client source code.
+ To suggest a change, edit the {{ index .Params.data_path 2 }}.rb file and submit a pull request to the Chef Infra Client repository.
+

+
+

+ {{ end }} + {{ if eq $product "infra" }} +

All Infra resources page

+ {{ else }} +

All {{ $product | title }} resources page

+ {{ end }} + {{ $file := .File.Path }} + {{ $dir := .File.Dir }} + {{ $resource_name := .Params.resource }} + + {{ $data_file := path.Join "content" $dir "data.yaml" }} + {{ $data := readFile $data_file | transform.Unmarshal }} + {{ $actions_list := index $data "actions_list" }} + {{ $properties_list := index $data "properties_list" }} + {{ $actions_list := index $data "actions_list" }} + + + {{ $resource_description_file := path.Join "content" $dir "resource_description.md" }} + + {{ if fileExists $resource_description_file }} + {{ readFile $resource_description_file | markdownify }} + {{ end }} + + +

Syntax

+ + {{ $syntax_description_file := path.Join "content" $dir "syntax_description.md" }} + + {{ if fileExists $syntax_description_file }} + {{ readFile $syntax_description_file | markdownify }} + {{ end }} + + {{ $pad_length := 26 }} + {{ $syntax_block := print "```ruby\n" }} + {{ $syntax_block = print $syntax_block $resource_name " 'name' do\n" }} + {{ range $properties_list }} + {{ $property_len := len .property }} + {{ $spaces := " " }} + {{ if gt $pad_length $property_len }} + {{ $spaces = strings.Repeat (sub $pad_length $property_len) " " }} + {{ end }} + {{ $syntax_block = print $syntax_block " " .property $spaces .ruby_type }} + {{ if .default_value }} + {{ $syntax_block = print $syntax_block " # default value: " .default_value "\n" }} + {{ else }} + {{ $syntax_block = print $syntax_block "\n" }} + {{ end }} + {{ end }} + + {{ $syntax_block = print $syntax_block " action" (strings.Repeat 20 " ") "Symbol\n" }} + {{ $syntax_block = print $syntax_block "end\n```" }} +

{{ markdownify $syntax_block }}

+ + +

Actions

+ +
+ {{ range $k, $v := $actions_list }} +
{{ $k }}
+ {{ if $v.markdown }} +
{{ $v.markdown | markdownify }}
+ {{ else if $v.file }} +
{{ readFile $v.file | markdownify }}
+ {{ end }} + {{ end }} +
+ + +

Properties

+ +
+ {{ range $properties_list }} +
{{ .property }}
+ + {{ if eq .required true }} +
REQUIRED
+ {{ end }} + +
Ruby Type: {{ .ruby_type }}
+ {{ with .default_value }} +
Default Value: {{ . }}
+ {{ end }} + {{ range .description_list }} + + {{ if .markdown }} +
{{ .markdown | markdownify }}
+ {{ else if .file }} +
{{ readFile .file | markdownify }}
+ {{ end }} + + {{ end }} + {{ end }} +
+ + + +

Examples

+ + {{ $examples_file := path.Join "content" $dir "examples.md" }} + + {{ if fileExists $examples_file }} + {{ readFile $examples_file | markdownify }} + {{ else }} +

This resource does not have any examples.

+ {{ end }} + +
+
+ {{ partialCached "feedback" . }} +
+{{ end }}