puppet-strings 2.9.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +257 -237
- data/README.md +52 -65
- data/lib/puppet/face/strings.rb +30 -50
- data/lib/puppet/feature/rgen.rb +1 -1
- data/lib/puppet/feature/yard.rb +1 -1
- data/lib/puppet-strings/describe.rb +18 -18
- data/lib/puppet-strings/markdown/base.rb +63 -28
- data/lib/puppet-strings/markdown/data_type.rb +4 -0
- data/lib/puppet-strings/markdown/defined_type.rb +4 -0
- data/lib/puppet-strings/markdown/function.rb +13 -8
- data/lib/puppet-strings/markdown/helpers.rb +21 -0
- data/lib/puppet-strings/markdown/puppet_class.rb +4 -0
- data/lib/puppet-strings/markdown/puppet_plan.rb +4 -0
- data/lib/puppet-strings/markdown/puppet_task.rb +4 -1
- data/lib/puppet-strings/markdown/resource_type.rb +13 -3
- data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +4 -4
- data/lib/puppet-strings/markdown/templates/data_type.erb +5 -9
- data/lib/puppet-strings/markdown/templates/data_type_function.erb +1 -1
- data/lib/puppet-strings/markdown/templates/function.erb +1 -1
- data/lib/puppet-strings/markdown/templates/puppet_task.erb +1 -1
- data/lib/puppet-strings/markdown/templates/resource_type.erb +6 -6
- data/lib/puppet-strings/markdown/templates/table_of_contents.erb +8 -8
- data/lib/puppet-strings/markdown.rb +62 -20
- data/lib/puppet-strings/monkey_patches/display_object_command.rb +4 -1
- data/lib/puppet-strings/tasks/generate.rb +8 -10
- data/lib/puppet-strings/tasks/gh_pages.rb +6 -5
- data/lib/puppet-strings/tasks/validate.rb +1 -1
- data/lib/puppet-strings/tasks.rb +5 -7
- data/lib/puppet-strings/version.rb +1 -1
- data/lib/puppet-strings/yard/code_objects/class.rb +2 -2
- data/lib/puppet-strings/yard/code_objects/data_type.rb +4 -4
- data/lib/puppet-strings/yard/code_objects/data_type_alias.rb +1 -1
- data/lib/puppet-strings/yard/code_objects/defined_type.rb +2 -2
- data/lib/puppet-strings/yard/code_objects/function.rb +11 -11
- data/lib/puppet-strings/yard/code_objects/group.rb +1 -1
- data/lib/puppet-strings/yard/code_objects/plan.rb +4 -2
- data/lib/puppet-strings/yard/code_objects/provider.rb +2 -2
- data/lib/puppet-strings/yard/code_objects/task.rb +6 -7
- data/lib/puppet-strings/yard/code_objects/type.rb +6 -6
- data/lib/puppet-strings/yard/handlers/helpers.rb +3 -4
- data/lib/puppet-strings/yard/handlers/json/base.rb +2 -1
- data/lib/puppet-strings/yard/handlers/json/task_handler.rb +4 -4
- data/lib/puppet-strings/yard/handlers/puppet/base.rb +7 -2
- data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb +3 -2
- data/lib/puppet-strings/yard/handlers/ruby/base.rb +3 -2
- data/lib/puppet-strings/yard/handlers/ruby/data_type_handler.rb +19 -16
- data/lib/puppet-strings/yard/handlers/ruby/function_handler.rb +70 -50
- data/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb +2 -1
- data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb +12 -9
- data/lib/puppet-strings/yard/handlers/ruby/type_base.rb +27 -27
- data/lib/puppet-strings/yard/handlers/ruby/type_extras_handler.rb +2 -3
- data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +2 -1
- data/lib/puppet-strings/yard/parsers/json/parser.rb +3 -2
- data/lib/puppet-strings/yard/parsers/json/task_statement.rb +3 -3
- data/lib/puppet-strings/yard/parsers/puppet/parser.rb +7 -7
- data/lib/puppet-strings/yard/parsers/puppet/statement.rb +16 -23
- data/lib/puppet-strings/yard/parsers.rb +1 -0
- data/lib/puppet-strings/yard/tags/enum_tag.rb +1 -2
- data/lib/puppet-strings/yard/tags/factory.rb +1 -1
- data/lib/puppet-strings/yard/tags/overload_tag.rb +7 -7
- data/lib/puppet-strings/yard/tags/parameter_directive.rb +2 -2
- data/lib/puppet-strings/yard/tags/property_directive.rb +2 -2
- data/lib/puppet-strings/yard/tags/summary_tag.rb +1 -2
- data/lib/puppet-strings/yard/util.rb +11 -4
- data/lib/puppet-strings/yard.rb +6 -6
- data/lib/puppet-strings.rb +7 -13
- metadata +13 -20
- data/lib/puppet-strings/markdown/data_types.rb +0 -43
- data/lib/puppet-strings/markdown/defined_types.rb +0 -39
- data/lib/puppet-strings/markdown/functions.rb +0 -40
- data/lib/puppet-strings/markdown/puppet_classes.rb +0 -39
- data/lib/puppet-strings/markdown/puppet_plans.rb +0 -39
- data/lib/puppet-strings/markdown/puppet_tasks.rb +0 -36
- data/lib/puppet-strings/markdown/resource_types.rb +0 -39
- data/lib/puppet-strings/markdown/table_of_contents.rb +0 -26
@@ -3,9 +3,13 @@
|
|
3
3
|
require 'puppet-strings/markdown/base'
|
4
4
|
|
5
5
|
module PuppetStrings::Markdown
|
6
|
+
# Generates Markdown for a Puppet Function.
|
6
7
|
class Function < Base
|
7
8
|
attr_reader :signatures
|
8
9
|
|
10
|
+
group_name 'Functions'
|
11
|
+
yard_types [:puppet_function]
|
12
|
+
|
9
13
|
def initialize(registry)
|
10
14
|
@template = 'function.erb'
|
11
15
|
super(registry, 'function')
|
@@ -21,14 +25,14 @@ module PuppetStrings::Markdown
|
|
21
25
|
|
22
26
|
def type
|
23
27
|
t = @registry[:type]
|
24
|
-
if
|
25
|
-
|
26
|
-
elsif
|
27
|
-
|
28
|
-
elsif
|
29
|
-
|
28
|
+
if %r{ruby4x}.match?(t)
|
29
|
+
'Ruby 4.x API'
|
30
|
+
elsif %r{ruby3}.match?(t)
|
31
|
+
'Ruby 3.x API'
|
32
|
+
elsif %r{ruby}.match?(t)
|
33
|
+
'Ruby'
|
30
34
|
else
|
31
|
-
|
35
|
+
'Puppet Language'
|
32
36
|
end
|
33
37
|
end
|
34
38
|
|
@@ -37,10 +41,11 @@ module PuppetStrings::Markdown
|
|
37
41
|
end
|
38
42
|
|
39
43
|
def error_text(text)
|
40
|
-
|
44
|
+
text.split(' ').drop(1).join(' ').to_s
|
41
45
|
end
|
42
46
|
end
|
43
47
|
|
48
|
+
# Implements methods to retrieve information about a function signature.
|
44
49
|
class Function::Signature < Base
|
45
50
|
def initialize(registry)
|
46
51
|
@registry = registry
|
@@ -0,0 +1,21 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Helpers for rendering Markdown
|
4
|
+
module PuppetStrings::Markdown::Helpers
|
5
|
+
# Formats code as either inline or a block.
|
6
|
+
#
|
7
|
+
# Note that this does not do any escaping even if the code contains ` or ```.
|
8
|
+
#
|
9
|
+
# @param [String] code The code to format.
|
10
|
+
# @param [Symbol] type The type of the code, e.g. :text, :puppet, or :ruby.
|
11
|
+
# @param [String] block_prefix String to insert before if it’s a block.
|
12
|
+
# @param [String] inline_prefix String to insert before if it’s inline.
|
13
|
+
# @returns [String] Markdown
|
14
|
+
def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ')
|
15
|
+
if code.include?("\n")
|
16
|
+
"#{block_prefix}```#{type}\n#{code}\n```"
|
17
|
+
else
|
18
|
+
"#{inline_prefix}`#{code}`"
|
19
|
+
end
|
20
|
+
end
|
21
|
+
end
|
@@ -3,7 +3,11 @@
|
|
3
3
|
require 'puppet-strings/markdown/base'
|
4
4
|
|
5
5
|
module PuppetStrings::Markdown
|
6
|
+
# Generates Markdown for a Puppet Class.
|
6
7
|
class PuppetClass < Base
|
8
|
+
group_name 'Classes'
|
9
|
+
yard_types [:puppet_class]
|
10
|
+
|
7
11
|
def initialize(registry)
|
8
12
|
@template = 'classes_and_defines.erb'
|
9
13
|
super(registry, 'class')
|
@@ -3,7 +3,11 @@
|
|
3
3
|
require 'puppet-strings/markdown/base'
|
4
4
|
|
5
5
|
module PuppetStrings::Markdown
|
6
|
+
# Generates Markdown for a Puppet Plan.
|
6
7
|
class PuppetPlan < Base
|
8
|
+
group_name 'Plans'
|
9
|
+
yard_types [:puppet_plan]
|
10
|
+
|
7
11
|
def initialize(registry)
|
8
12
|
@template = 'classes_and_defines.erb'
|
9
13
|
super(registry, 'plan')
|
@@ -3,7 +3,11 @@
|
|
3
3
|
require 'puppet-strings/markdown/base'
|
4
4
|
|
5
5
|
module PuppetStrings::Markdown
|
6
|
+
# Generates Markdown for a Puppet Task.
|
6
7
|
class PuppetTask < Base
|
8
|
+
group_name 'Tasks'
|
9
|
+
yard_types [:puppet_task]
|
10
|
+
|
7
11
|
def initialize(registry)
|
8
12
|
@template = 'puppet_task.erb'
|
9
13
|
@registry = registry
|
@@ -21,6 +25,5 @@ module PuppetStrings::Markdown
|
|
21
25
|
def input_method
|
22
26
|
@registry[:input_method]
|
23
27
|
end
|
24
|
-
|
25
28
|
end
|
26
29
|
end
|
@@ -3,7 +3,11 @@
|
|
3
3
|
require 'puppet-strings/markdown/base'
|
4
4
|
|
5
5
|
module PuppetStrings::Markdown
|
6
|
+
# Generates Markdown for a Puppet Resource Type.
|
6
7
|
class ResourceType < Base
|
8
|
+
group_name 'Resource types'
|
9
|
+
yard_types [:puppet_type]
|
10
|
+
|
7
11
|
def initialize(registry)
|
8
12
|
@template = 'resource_type.erb'
|
9
13
|
super(registry, 'type')
|
@@ -29,17 +33,23 @@ module PuppetStrings::Markdown
|
|
29
33
|
def properties_and_checks
|
30
34
|
return nil if properties.nil? && checks.nil?
|
31
35
|
|
32
|
-
((properties || []) + (checks || [])).sort_by { |p| p[:name] }
|
36
|
+
((properties || []) + (checks || [])).sort_by { |p| p[:name] }.map do |prop|
|
37
|
+
prop[:link] = clean_link("$#{name}::#{prop[:name]}")
|
38
|
+
prop
|
39
|
+
end
|
33
40
|
end
|
34
41
|
|
35
42
|
def parameters
|
36
43
|
return nil unless @registry[:parameters]
|
37
44
|
|
38
|
-
@registry[:parameters].sort_by { |p| p[:name] }
|
45
|
+
@registry[:parameters].sort_by { |p| p[:name] }.map do |param|
|
46
|
+
param[:link] = clean_link("$#{name}::#{param[:name]}")
|
47
|
+
param
|
48
|
+
end
|
39
49
|
end
|
40
50
|
|
41
51
|
def regex_in_data_type?(data_type)
|
42
|
-
m = data_type.match(
|
52
|
+
m = data_type.match(%r{\w+\[/.*/\]})
|
43
53
|
m unless m.nil? || m.length.zero?
|
44
54
|
end
|
45
55
|
end
|
@@ -50,14 +50,14 @@
|
|
50
50
|
The following parameters are available in the `<%= name %>` <%= @type %>:
|
51
51
|
|
52
52
|
<% params.each do |param| -%>
|
53
|
-
* [`<%= param[:name] %>`](#<%= param[:
|
53
|
+
* [`<%= param[:name] %>`](#<%= param[:link] %>)
|
54
54
|
<% end -%>
|
55
55
|
|
56
56
|
<% params.each do |param| -%>
|
57
|
-
##### <a name="<%= param[:
|
57
|
+
##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
|
58
58
|
|
59
59
|
<% if param[:types] -%>
|
60
|
-
Data type
|
60
|
+
Data type:<%= code_maybe_block(param[:types].join(', ')) %>
|
61
61
|
|
62
62
|
<% end -%>
|
63
63
|
<%= param[:text] %>
|
@@ -79,7 +79,7 @@ Options:
|
|
79
79
|
|
80
80
|
<% end -%>
|
81
81
|
<% if defaults && defaults[param[:name]] -%>
|
82
|
-
Default value
|
82
|
+
Default value:<%= code_maybe_block(defaults[param[:name]]) %>
|
83
83
|
|
84
84
|
<% end -%>
|
85
85
|
<% end -%>
|
@@ -45,11 +45,7 @@
|
|
45
45
|
<% end -%>
|
46
46
|
<% end -%>
|
47
47
|
<% if alias_of -%>
|
48
|
-
Alias of
|
49
|
-
|
50
|
-
```puppet
|
51
|
-
<%= alias_of %>
|
52
|
-
```
|
48
|
+
Alias of<%= code_maybe_block(alias_of) %>
|
53
49
|
|
54
50
|
<% end -%>
|
55
51
|
<% if params -%>
|
@@ -58,14 +54,14 @@ Alias of
|
|
58
54
|
The following parameters are available in the `<%= name %>` <%= @type %>:
|
59
55
|
|
60
56
|
<% params.each do |param| -%>
|
61
|
-
* [`<%= param[:name] %>`](#<%= param[:
|
57
|
+
* [`<%= param[:name] %>`](#<%= param[:link] %>)
|
62
58
|
<% end -%>
|
63
59
|
|
64
60
|
<% params.each do |param| -%>
|
65
|
-
##### <a name="<%= param[:
|
61
|
+
##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
|
66
62
|
|
67
63
|
<% if param[:types] -%>
|
68
|
-
Data type
|
64
|
+
Data type:<%= code_maybe_block(param[:types].join(', ')) %>
|
69
65
|
|
70
66
|
<% end -%>
|
71
67
|
<%= param[:text] %>
|
@@ -87,7 +83,7 @@ Options:
|
|
87
83
|
|
88
84
|
<% end -%>
|
89
85
|
<% if defaults && defaults[param[:name]] -%>
|
90
|
-
Default value
|
86
|
+
Default value:<%= code_maybe_block(defaults[param[:name]]) %>
|
91
87
|
|
92
88
|
<% end -%>
|
93
89
|
<% end -%>
|
@@ -53,7 +53,7 @@ The following properties are available in the `<%= name %>` <%= @type %>.
|
|
53
53
|
##### `<%= prop[:name] %>`
|
54
54
|
|
55
55
|
<% if prop[:values] -%>
|
56
|
-
Valid values: `<%= prop[:values].
|
56
|
+
Valid values: `<%= prop[:values].join('`, `') %>`
|
57
57
|
|
58
58
|
<% end -%>
|
59
59
|
<% if prop[:isnamevar] -%>
|
@@ -87,7 +87,7 @@ Options:
|
|
87
87
|
|
88
88
|
<% end -%>
|
89
89
|
<% if prop[:default] -%>
|
90
|
-
Default value
|
90
|
+
Default value:<%= code_maybe_block(prop[:default], type: :ruby) %>
|
91
91
|
|
92
92
|
<% end -%>
|
93
93
|
<% end -%>
|
@@ -98,14 +98,14 @@ Default value: `<%= prop[:default] %>`
|
|
98
98
|
The following parameters are available in the `<%= name %>` <%= @type %>.
|
99
99
|
|
100
100
|
<% parameters.each do |param| -%>
|
101
|
-
* [`<%= param[:name] %>`](#<%= param[:
|
101
|
+
* [`<%= param[:name] %>`](#<%= param[:link] %>)
|
102
102
|
<% end -%>
|
103
103
|
|
104
104
|
<% parameters.each do |param| -%>
|
105
|
-
##### <a name="<%= param[:
|
105
|
+
##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
|
106
106
|
|
107
107
|
<% if param[:values] -%>
|
108
|
-
Valid values: `<%= param[:values].
|
108
|
+
Valid values: `<%= param[:values].join('`, `') %>`
|
109
109
|
|
110
110
|
<% end -%>
|
111
111
|
<% if param[:isnamevar] -%>
|
@@ -141,7 +141,7 @@ Options:
|
|
141
141
|
|
142
142
|
<% end -%>
|
143
143
|
<% if param[:default] -%>
|
144
|
-
Default value: `<%=
|
144
|
+
Default value: `<%= param[:default] %>`
|
145
145
|
|
146
146
|
<% end -%>
|
147
147
|
<% if param[:required_features] -%>
|
@@ -1,26 +1,26 @@
|
|
1
|
-
<%
|
1
|
+
<% unless items.empty? -%>
|
2
2
|
### <%= group_name %>
|
3
|
+
<% if has_public -%>
|
4
|
+
<% if has_private # only display public heading if we have both -%>
|
3
5
|
|
4
|
-
<% if priv -%>
|
5
6
|
#### Public <%= group_name %>
|
7
|
+
<% end -%>
|
6
8
|
|
7
|
-
<%
|
9
|
+
<% items.each do |item| -%>
|
8
10
|
<% unless item[:private] -%>
|
9
11
|
* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
|
10
12
|
<% end -%>
|
11
13
|
<% end -%>
|
14
|
+
<% end -%>
|
15
|
+
<% if has_private -%>
|
12
16
|
|
13
17
|
#### Private <%= group_name %>
|
14
18
|
|
15
|
-
<%
|
19
|
+
<% items.each do |item| -%>
|
16
20
|
<% if item[:private] -%>
|
17
21
|
* `<%= item[:name] %>`<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
|
18
22
|
<% end -%>
|
19
23
|
<% end -%>
|
20
|
-
<% else -%>
|
21
|
-
<% group.each do |item| -%>
|
22
|
-
* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
|
23
|
-
<% end -%>
|
24
24
|
<% end -%>
|
25
25
|
|
26
26
|
<% end -%>
|
@@ -4,30 +4,59 @@ require 'puppet-strings/json'
|
|
4
4
|
|
5
5
|
# module for parsing Yard Registries and generating markdown
|
6
6
|
module PuppetStrings::Markdown
|
7
|
-
require_relative 'markdown/
|
8
|
-
require_relative 'markdown/
|
9
|
-
require_relative 'markdown/
|
10
|
-
require_relative 'markdown/
|
11
|
-
require_relative 'markdown/
|
12
|
-
require_relative 'markdown/
|
13
|
-
require_relative 'markdown/
|
14
|
-
|
7
|
+
require_relative 'markdown/puppet_class'
|
8
|
+
require_relative 'markdown/function'
|
9
|
+
require_relative 'markdown/defined_type'
|
10
|
+
require_relative 'markdown/data_type'
|
11
|
+
require_relative 'markdown/resource_type'
|
12
|
+
require_relative 'markdown/puppet_task'
|
13
|
+
require_relative 'markdown/puppet_plan'
|
14
|
+
|
15
|
+
# Get classes that handle collecting and rendering each section/group.
|
16
|
+
#
|
17
|
+
# @return [Array[class]] The classes
|
18
|
+
def self.groups
|
19
|
+
[
|
20
|
+
PuppetStrings::Markdown::PuppetClass,
|
21
|
+
PuppetStrings::Markdown::DefinedType,
|
22
|
+
PuppetStrings::Markdown::ResourceType,
|
23
|
+
PuppetStrings::Markdown::Function,
|
24
|
+
PuppetStrings::Markdown::DataType,
|
25
|
+
PuppetStrings::Markdown::PuppetTask,
|
26
|
+
PuppetStrings::Markdown::PuppetPlan,
|
27
|
+
]
|
28
|
+
end
|
15
29
|
|
16
30
|
# generates markdown documentation
|
17
31
|
# @return [String] markdown doc
|
18
32
|
def self.generate
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
33
|
+
output = [
|
34
|
+
"# Reference\n\n",
|
35
|
+
"<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n",
|
36
|
+
"## Table of Contents\n\n",
|
37
|
+
]
|
38
|
+
|
39
|
+
# Create table of contents
|
40
|
+
template = erb(File.join(__dir__, 'markdown', 'templates', 'table_of_contents.erb'))
|
41
|
+
groups.each do |group|
|
42
|
+
group_name = group.group_name
|
43
|
+
items = group.items.map { |item| item.toc_info }
|
44
|
+
has_private = items.any? { |item| item[:private] }
|
45
|
+
has_public = items.any? { |item| !item[:private] }
|
46
|
+
|
47
|
+
output << template.result(binding)
|
48
|
+
end
|
49
|
+
|
50
|
+
# Create actual contents
|
51
|
+
groups.each do |group|
|
52
|
+
items = group.items.reject { |item| item.private? }
|
53
|
+
unless items.empty?
|
54
|
+
output << "## #{group.group_name}\n\n"
|
55
|
+
output.append(items.map { |item| item.render })
|
56
|
+
end
|
57
|
+
end
|
58
|
+
|
59
|
+
output.join('')
|
31
60
|
end
|
32
61
|
|
33
62
|
# mimicks the behavior of the json render, although path will never be nil
|
@@ -41,4 +70,17 @@ module PuppetStrings::Markdown
|
|
41
70
|
YARD::Logger.instance.debug "Wrote markdown to #{path}"
|
42
71
|
end
|
43
72
|
end
|
73
|
+
|
74
|
+
# Helper function to load an ERB template.
|
75
|
+
#
|
76
|
+
# @param [String] path The full path to the template file.
|
77
|
+
# @return [ERB] Template
|
78
|
+
def self.erb(path)
|
79
|
+
if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
|
80
|
+
ERB.new(File.read(path), trim_mode: '-')
|
81
|
+
else
|
82
|
+
# This outputs warnings in Ruby 2.6+.
|
83
|
+
ERB.new(File.read(path), nil, '-')
|
84
|
+
end
|
85
|
+
end
|
44
86
|
end
|
@@ -4,9 +4,12 @@
|
|
4
4
|
# namespace, but this is disabled in our base object, and so instead gets
|
5
5
|
# URL-encoded.
|
6
6
|
require 'yard/server/commands/display_object_command'
|
7
|
+
|
8
|
+
# Monkey patch YARD::Server::Commands::DisplayObjectCommand object_path.
|
7
9
|
class YARD::Server::Commands::DisplayObjectCommand
|
8
10
|
private
|
9
|
-
|
11
|
+
|
12
|
+
alias object_path_yard object_path
|
10
13
|
def object_path
|
11
14
|
object_path_yard.gsub('_3A', ':')
|
12
15
|
end
|
@@ -5,7 +5,7 @@ require 'puppet-strings'
|
|
5
5
|
# Implements the strings:generate task.
|
6
6
|
namespace :strings do
|
7
7
|
desc 'Generate Puppet documentation with YARD.'
|
8
|
-
task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |
|
8
|
+
task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |_t, args|
|
9
9
|
patterns = args[:patterns]
|
10
10
|
patterns = patterns.split if patterns
|
11
11
|
patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
|
@@ -16,7 +16,7 @@ namespace :strings do
|
|
16
16
|
markup: args[:markup] || 'markdown',
|
17
17
|
}
|
18
18
|
|
19
|
-
raise(
|
19
|
+
raise('Error: Both JSON and Markdown output have been selected. Please select one.') if args[:json] == 'true' && args[:markdown] == 'true'
|
20
20
|
|
21
21
|
# rubocop:disable Style/PreferredHashMethods
|
22
22
|
# Because of Ruby, true and false from the args are both strings and both true. Here,
|
@@ -28,16 +28,14 @@ namespace :strings do
|
|
28
28
|
# @param [Symbol] possible format option
|
29
29
|
# @return nil
|
30
30
|
def parse_format_option(args, options, format)
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
35
|
-
end
|
36
|
-
end
|
31
|
+
return unless args.has_key? format
|
32
|
+
options[format] = args[format] == 'false' || args[format].empty? ? false : true
|
33
|
+
return unless options[format]
|
34
|
+
options[:path] = args[format] == 'true' ? nil : args[format]
|
37
35
|
end
|
38
36
|
# rubocop:enable Style/PreferredHashMethods
|
39
37
|
|
40
|
-
|
38
|
+
[:json, :markdown].each { |format| parse_format_option(args, options, format) }
|
41
39
|
|
42
40
|
warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
|
43
41
|
options[:yard_args] = args[:yard_args].split if args.key? :yard_args
|
@@ -47,7 +45,7 @@ namespace :strings do
|
|
47
45
|
|
48
46
|
namespace :generate do
|
49
47
|
desc 'Generate Puppet Reference documentation.'
|
50
|
-
task :reference, [:patterns, :debug, :backtrace] do |
|
48
|
+
task :reference, [:patterns, :debug, :backtrace] do |_t, args|
|
51
49
|
Rake::Task['strings:generate'].invoke(args[:patterns], args[:debug], args[:backtrace], nil, 'false', 'true')
|
52
50
|
end
|
53
51
|
end
|
@@ -1,12 +1,13 @@
|
|
1
1
|
# frozen_string_literal: true
|
2
2
|
|
3
|
+
require 'English'
|
3
4
|
require 'puppet-strings/tasks'
|
4
5
|
|
5
6
|
namespace :strings do
|
6
7
|
namespace :gh_pages do
|
7
8
|
task :checkout do
|
8
9
|
if Dir.exist?('doc')
|
9
|
-
|
10
|
+
raise "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
|
10
11
|
|
11
12
|
Dir.chdir('doc') do
|
12
13
|
system 'git checkout gh-pages'
|
@@ -14,7 +15,7 @@ namespace :strings do
|
|
14
15
|
end
|
15
16
|
else
|
16
17
|
git_uri = `git config --get remote.origin.url`.strip
|
17
|
-
|
18
|
+
raise "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $CHILD_STATUS.success?
|
18
19
|
|
19
20
|
Dir.mkdir('doc')
|
20
21
|
Dir.chdir('doc') do
|
@@ -29,7 +30,7 @@ namespace :strings do
|
|
29
30
|
task :configure do
|
30
31
|
unless File.exist?(File.join('doc', '_config.yml'))
|
31
32
|
Dir.chdir('doc') do
|
32
|
-
File.open('_config.yml', 'w+') {|f| f.write(
|
33
|
+
File.open('_config.yml', 'w+') { |f| f.write('include: _index.html') }
|
33
34
|
end
|
34
35
|
end
|
35
36
|
end
|
@@ -37,7 +38,7 @@ namespace :strings do
|
|
37
38
|
task :push do
|
38
39
|
output = `git describe --long 2>/dev/null`
|
39
40
|
# If a project has never been tagged, fall back to latest SHA
|
40
|
-
output.empty? ?
|
41
|
+
git_sha = output.empty? ? `git log --pretty=format:'%H' -n 1` : output
|
41
42
|
|
42
43
|
Dir.chdir('doc') do
|
43
44
|
system 'git add .'
|
@@ -47,7 +48,7 @@ namespace :strings do
|
|
47
48
|
end
|
48
49
|
|
49
50
|
desc 'Update docs on the gh-pages branch and push to GitHub.'
|
50
|
-
task :
|
51
|
+
task update: [
|
51
52
|
:checkout,
|
52
53
|
:'strings:generate',
|
53
54
|
:configure,
|
@@ -6,7 +6,7 @@ require 'tempfile'
|
|
6
6
|
namespace :strings do
|
7
7
|
namespace :validate do
|
8
8
|
desc 'Validate the reference is up to date'
|
9
|
-
task :reference, [:patterns, :debug, :backtrace] do |
|
9
|
+
task :reference, [:patterns, :debug, :backtrace] do |_t, args|
|
10
10
|
filename = 'REFERENCE.md'
|
11
11
|
|
12
12
|
unless File.exist?(filename)
|
data/lib/puppet-strings/tasks.rb
CHANGED
@@ -3,11 +3,9 @@
|
|
3
3
|
require 'rake'
|
4
4
|
require 'rake/tasklib'
|
5
5
|
|
6
|
-
module
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
require 'puppet-strings/tasks/validate.rb'
|
12
|
-
end
|
6
|
+
# The module for Puppet Strings rake tasks.
|
7
|
+
module PuppetStrings::Tasks
|
8
|
+
require 'puppet-strings/tasks/generate.rb'
|
9
|
+
require 'puppet-strings/tasks/gh_pages.rb'
|
10
|
+
require 'puppet-strings/tasks/validate.rb'
|
13
11
|
end
|
@@ -13,7 +13,7 @@ class PuppetStrings::Yard::CodeObjects::Classes < PuppetStrings::Yard::CodeObjec
|
|
13
13
|
# Gets the display name of the group.
|
14
14
|
# @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
|
15
15
|
# @return [String] Returns the display name of the group.
|
16
|
-
def name(
|
16
|
+
def name(_prefix = false)
|
17
17
|
'Puppet Classes'
|
18
18
|
end
|
19
19
|
end
|
@@ -53,7 +53,7 @@ class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects
|
|
53
53
|
hash[:line] = line
|
54
54
|
hash[:inherits] = statement.parent_class if statement.parent_class
|
55
55
|
hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
|
56
|
-
defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
|
56
|
+
defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
|
57
57
|
hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
|
58
58
|
hash[:source] = source unless source.nil? || source.empty?
|
59
59
|
hash
|
@@ -14,7 +14,7 @@ class PuppetStrings::Yard::CodeObjects::DataTypes < PuppetStrings::Yard::CodeObj
|
|
14
14
|
# Gets the display name of the group.
|
15
15
|
# @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
|
16
16
|
# @return [String] Returns the display name of the group.
|
17
|
-
def name(
|
17
|
+
def name(_prefix = false)
|
18
18
|
'Puppet Data Types'
|
19
19
|
end
|
20
20
|
end
|
@@ -73,7 +73,7 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
|
|
73
73
|
meth_obj.add_tag(YARD::Tags::Tag.new(:param, '', [param_type], "param#{index + 1}"))
|
74
74
|
end
|
75
75
|
|
76
|
-
|
76
|
+
meths << meth_obj
|
77
77
|
end
|
78
78
|
|
79
79
|
def functions
|
@@ -87,14 +87,14 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
|
|
87
87
|
hash[:name] = name
|
88
88
|
hash[:file] = file
|
89
89
|
hash[:line] = line
|
90
|
-
hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring,
|
90
|
+
hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, [:param, :option, :enum, :return, :example])
|
91
91
|
hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
|
92
92
|
hash[:source] = source unless source.nil? || source.empty?
|
93
93
|
hash[:functions] = functions.map do |func|
|
94
94
|
{
|
95
95
|
name: func.name,
|
96
96
|
signature: func.signature,
|
97
|
-
docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring,
|
97
|
+
docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring, [:param, :option, :enum, :return, :example])
|
98
98
|
}
|
99
99
|
end
|
100
100
|
hash
|
@@ -14,7 +14,7 @@ class PuppetStrings::Yard::CodeObjects::DataTypeAliases < PuppetStrings::Yard::C
|
|
14
14
|
# Gets the display name of the group.
|
15
15
|
# @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
|
16
16
|
# @return [String] Returns the display name of the group.
|
17
|
-
def name(
|
17
|
+
def name(_prefix = false)
|
18
18
|
'Puppet Data Type Aliases'
|
19
19
|
end
|
20
20
|
end
|