Skip to content

Commit 8d17fc2

Browse files
joshcooperjoshcooper
authored
Merge pull request #9466 from joshcooper/puppet_man
(PUP-12075) Render puppet man page correctly
2 parents bc13bea + 6534391 commit 8d17fc2

File tree

6 files changed

+217
-40
lines changed

6 files changed

+217
-40
lines changed

‎lib/puppet/face/help.rb

Lines changed: 43 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,33 @@ def legacy_applications
151151
end.sort
152152
end
153153

154+
def generate_summary(appname)
155+
if is_face_app?(appname)
156+
begin
157+
face = Puppet::Face[appname, :current]
158+
# Add deprecation message to summary if the face is deprecated
159+
summary = face.deprecated? ? face.summary + ' ' + _("(Deprecated)") : face.summary
160+
[appname, summary, ' ']
161+
rescue StandardError, LoadError
162+
error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
163+
error_message += ' ' + _("Check error logs.")
164+
[error_message, '', ' ']
165+
end
166+
else
167+
begin
168+
summary = Puppet::Application[appname].summary
169+
if summary.empty?
170+
summary = horribly_extract_summary_from(appname)
171+
end
172+
[appname, summary, ' ']
173+
rescue StandardError, LoadError
174+
error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
175+
error_message += ' ' + _("Check error logs.")
176+
[error_message, '', ' ']
177+
end
178+
end
179+
end
180+
154181
# Return a list of all applications (both legacy and Face applications), along with a summary
155182
# of their functionality.
156183
# @return [Array] An Array of Arrays. The outer array contains one entry per application; each
@@ -162,45 +189,38 @@ def all_application_summaries
162189

163190
if appname == COMMON || appname == SPECIALIZED || appname == BLANK
164191
result << appname
165-
elsif is_face_app?(appname)
166-
begin
167-
face = Puppet::Face[appname, :current]
168-
# Add deprecation message to summary if the face is deprecated
169-
summary = face.deprecated? ? face.summary + ' ' + _("(Deprecated)") : face.summary
170-
result << [appname, summary, ' ']
171-
rescue StandardError, LoadError
172-
error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
173-
error_message += ' ' + _("Check error logs.")
174-
result << [error_message, '', ' ']
175-
end
176192
else
177-
begin
178-
summary = Puppet::Application[appname].summary
179-
if summary.empty?
180-
summary = horribly_extract_summary_from(appname)
181-
end
182-
result << [appname, summary, ' ']
183-
rescue StandardError, LoadError
184-
error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
185-
error_message += ' ' + _("Check error logs.")
186-
result << [error_message, '', ' ']
187-
end
193+
result << generate_summary(appname)
188194
end
189195
end
190196
end
191197

192198
COMMON = 'Common:'
193199
SPECIALIZED = 'Specialized:'
194200
BLANK = "\n"
201+
COMMON_APPS = %w[apply agent config help lookup module resource]
195202
def available_application_names_special_sort
196203
full_list = Puppet::Application.available_application_names
197-
a_list = full_list & %w[apply agent config help lookup module resource]
204+
a_list = full_list & COMMON_APPS
198205
a_list = a_list.sort
199206
also_ran = full_list - a_list
200207
also_ran = also_ran.sort
201208
[[COMMON], a_list, [BLANK], [SPECIALIZED], also_ran].flatten(1)
202209
end
203210

211+
def common_app_summaries
212+
COMMON_APPS.map do |appname|
213+
generate_summary(appname)
214+
end
215+
end
216+
217+
def specialized_app_summaries
218+
specialized_apps = Puppet::Application.available_application_names - COMMON_APPS
219+
specialized_apps.filter_map do |appname|
220+
generate_summary(appname) unless exclude_from_docs?(appname)
221+
end
222+
end
223+
204224
def horribly_extract_summary_from(appname)
205225
help = Puppet::Application[appname].help.split("\n")
206226
# Now we find the line with our summary, extract it, and return it. This

‎lib/puppet/reference/configuration.rb

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@
4343
val = "the Host's fully qualified domain name, as determined by Facter"
4444
when 'srv_domain'
4545
val = 'example.com'
46+
when 'http_user_agent'
47+
val = 'Puppet/<version> Ruby/<version> (<architecture>)'
4648
end
4749

4850
# Leave out the section information; it was apparently confusing people.

‎man/man5/puppet.conf.5

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -973,7 +973,7 @@ The time to wait for data to be read from an HTTP connection\. If nothing is rea
973973
The HTTP User\-Agent string to send when making network requests\.
974974
.
975975
.IP "\(bu" 4
976-
\fIDefault\fR: \fBPuppet/8\.9\.0 Ruby/3\.1\.1\-p18 (x86_64\-linux)\fR
976+
\fIDefault\fR: \fBPuppet/<version> Ruby/<version> (<architecture>)\fR
977977
.
978978
.IP "" 0
979979
.

‎man/man8/puppet.8

Lines changed: 121 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,138 @@
44
.TH "PUPPET" "8" "August 2024" "Puppet, Inc." "Puppet manual"
55
.
66
.SH "NAME"
7-
\fBpuppet\fR
7+
\fBpuppet\fR \- an automated configuration management tool
8+
.
9+
.SH "SYNOPSIS"
10+
\fBpuppet\fR \fIsubcommand\fR [options] \fIaction\fR [options]
11+
.
12+
.SH "DESCRIPTION"
13+
Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs administrative tasks (such as adding users, installing packages, and updating server configurations) based on a centralized specification\.
14+
.
15+
.SH "COMMANDS"
16+
.
17+
.SS "Common"
18+
\fBapply\fR
19+
.
20+
.br
21+
\~\~\~\~Apply Puppet manifests locally
22+
.
23+
.P
24+
\fBagent\fR
25+
.
26+
.br
27+
\~\~\~\~The puppet agent daemon
28+
.
29+
.P
30+
\fBconfig\fR
31+
.
32+
.br
33+
\~\~\~\~Interact with Puppet\'s settings\.
34+
.
35+
.P
36+
\fBhelp\fR
37+
.
38+
.br
39+
\~\~\~\~Display Puppet help\.
40+
.
41+
.P
42+
\fBlookup\fR
43+
.
44+
.br
45+
\~\~\~\~Interactive Hiera lookup
46+
.
47+
.P
48+
\fBmodule\fR
49+
.
50+
.br
51+
\~\~\~\~Creates, installs and searches for modules on the Puppet Forge\.
52+
.
53+
.P
54+
\fBresource\fR
55+
.
56+
.br
57+
\~\~\~\~The resource abstraction layer shell
58+
.
59+
.SS "Specialized"
60+
\fBcatalog\fR
61+
.
62+
.br
63+
\~\~\~\~Compile, save, view, and convert catalogs\.
64+
.
65+
.P
66+
\fBdescribe\fR
67+
.
68+
.br
69+
\~\~\~\~Display help about resource types
70+
.
71+
.P
72+
\fBdevice\fR
73+
.
74+
.br
75+
\~\~\~\~Manage remote network devices
76+
.
77+
.P
78+
\fBdoc\fR
79+
.
80+
.br
81+
\~\~\~\~Generate Puppet references
882
.
983
.P
10-
Usage: puppet \fIsubcommand\fR [options] \fIaction\fR [options]
84+
\fBepp\fR
85+
.
86+
.br
87+
\~\~\~\~Interact directly with the EPP template parser/renderer\.
1188
.
1289
.P
13-
Available subcommands:
90+
\fBfacts\fR
91+
.
92+
.br
93+
\~\~\~\~Retrieve and store facts\.
94+
.
95+
.P
96+
\fBfilebucket\fR
97+
.
98+
.br
99+
\~\~\~\~Store and retrieve files in a filebucket
14100
.
15101
.P
16-
Common:
102+
\fBgenerate\fR
17103
.
18104
.br
19-
agent The puppet agent daemon apply Apply Puppet manifests locally config Interact with Puppet\'s settings\. help Display Puppet help\. lookup Interactive Hiera lookup module Creates, installs and searches for modules on the Puppet Forge\. resource The resource abstraction layer shell
105+
\~\~\~\~Generates Puppet code from Ruby definitions\.
20106
.
21107
.P
22-
Specialized:
108+
\fBnode\fR
23109
.
24110
.br
25-
catalog Compile, save, view, and convert catalogs\. describe Display help about resource types device Manage remote network devices doc Generate Puppet references epp Interact directly with the EPP template parser/renderer\. facts Retrieve and store facts\. filebucket Store and retrieve files in a filebucket generate Generates Puppet code from Ruby definitions\. node View and manage node definitions\. parser Interact directly with the parser\. plugin Interact with the Puppet plugin system\. script Run a puppet manifests as a script without compiling a catalog ssl Manage SSL keys and certificates for puppet SSL clients
111+
\~\~\~\~View and manage node definitions\.
112+
.
113+
.P
114+
\fBparser\fR
115+
.
116+
.br
117+
\~\~\~\~Interact directly with the parser\.
118+
.
119+
.P
120+
\fBplugin\fR
121+
.
122+
.br
123+
\~\~\~\~Interact with the Puppet plugin system\.
124+
.
125+
.P
126+
\fBscript\fR
127+
.
128+
.br
129+
\~\~\~\~Run a puppet manifests as a script without compiling a catalog
130+
.
131+
.P
132+
\fBssl\fR
133+
.
134+
.br
135+
\~\~\~\~Manage SSL keys and certificates for puppet SSL clients
136+
.
137+
.SH "SEE ALSO"
138+
See \fBpuppet help <subcommand>\fR for help on a specific subcommand\.
26139
.
27140
.P
28-
See \'puppet help \fIsubcommand\fR \fIaction\fR\' for help on a specific subcommand action\. See \'puppet help \fIsubcommand\fR\' for help on a specific subcommand\. Puppet v8\.9\.0
141+
See \fBpuppet help <subcommand> <action>\fR for help on a specific subcommand action\.

‎rakelib/man/puppet.erb

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
puppet(8) - an automated configuration management tool
2+
=========
3+
4+
## SYNOPSIS
5+
6+
`puppet` <subcommand> [options] <action> [options]
7+
8+
## DESCRIPTION
9+
10+
Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs administrative tasks
11+
(such as adding users, installing packages, and updating server configurations) based on a centralized specification.
12+
13+
## COMMANDS
14+
15+
### Common
16+
17+
<% common.each do |appname, summary, _| -%>
18+
`<%= appname.to_s %>`<br>
19+
&nbsp;&nbsp;&nbsp;&nbsp;<%= summary %>
20+
21+
<% end -%>
22+
23+
### Specialized
24+
25+
<% specialized.each do |appname, summary, _| -%>
26+
`<%= appname.to_s %>`<br>
27+
&nbsp;&nbsp;&nbsp;&nbsp;<%= summary %>
28+
29+
<% end -%>
30+
31+
## SEE ALSO
32+
See `puppet help <subcommand>` for help on a specific subcommand.
33+
34+
See `puppet help <subcommand> <action>` for help on a specific subcommand action.

‎rakelib/manpages.rake

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ task :gen_manpages do
66
Puppet.initialize_settings
77
helpface = Puppet::Face[:help, '0.0.1']
88

9-
bins = Dir.glob(%w{bin/*})
109
non_face_applications = helpface.legacy_applications
1110
faces = Puppet::Face.faces.map(&:to_s)
1211
apps = non_face_applications + faces
@@ -30,19 +29,28 @@ task :gen_manpages do
3029
abort("Ronn does not appear to be installed")
3130
end
3231

32+
# ronn shells out to groff
33+
groff = %x{which groff}.chomp
34+
unless File.executable?(groff)
35+
abort("Groff does not appear to be installed")
36+
end
37+
3338
%x{mkdir -p ./man/man5 ./man/man8}
3439
%x{RUBYLIB=./lib:$RUBYLIB bin/puppet doc --reference configuration > ./man/man5/puppetconf.5.ronn}
3540
%x{#{ronn} #{ronn_args} ./man/man5/puppetconf.5.ronn}
3641
FileUtils.mv("./man/man5/puppetconf.5", "./man/man5/puppet.conf.5")
3742
FileUtils.rm("./man/man5/puppetconf.5.ronn")
3843

39-
# Create LEGACY binary man pages (i.e. delete me for 2.8.0)
40-
bins.each do |bin|
41-
b = bin.gsub( /^s?bin\//, "")
42-
%x{RUBYLIB=./lib:$RUBYLIB #{bin} --help > ./man/man8/#{b}.8.ronn}
43-
%x{#{ronn} #{ronn_args} ./man/man8/#{b}.8.ronn}
44-
FileUtils.rm("./man/man8/#{b}.8.ronn")
45-
end
44+
# Create puppet binary man page
45+
# puppet --help outputs raw text, not ronn, so trying to convert that to roff
46+
# fails miserably. Render valid ronn so we can convert to roff
47+
common = helpface.common_app_summaries
48+
specialized = helpface.specialized_app_summaries
49+
template_binding = OpenStruct.new(common: common, specialized: specialized).instance_eval {binding}
50+
content = ERB.new(File.read(File.join(__dir__, 'man/puppet.erb')), trim_mode: '-').result(template_binding)
51+
File.write("./man/man8/puppet.8.ronn", content)
52+
%x{#{ronn} #{ronn_args} ./man/man8/puppet.8.ronn}
53+
FileUtils.rm("./man/man8/puppet.8.ronn")
4654

4755
apps.each do |app|
4856
%x{RUBYLIB=./lib:$RUBYLIB bin/puppet help #{app} --ronn > ./man/man8/puppet-#{app}.8.ronn}

0 commit comments

Comments
 (0)