Jira (PDOC-279) "puppet strings" command unavailable after following installation docs

[Garrett Guillotte (JIRA)]

Garrett Guillotte created an issue

Puppet Strings / PDOC-279 "puppet strings" command unavailable after following installation docs Issue Type: Bug Assignee: Unassigned Components: DOCS Created: 2019/05/30 6:49 PM Priority: Normal Reporter: Garrett Guillotte Problem statement Following the instructions at https://puppet.com/docs/puppet/6.4/puppet_strings.html does not result in a functional puppet strings command. Users following this documentation cannot use puppet strings to generate module documentation. Expected result Either following the documented installation instructions works, or if installing and invoking puppet strings directly is no longer recommended, we point users to PDK or whatever the preferred module docs generation method is now. Observed result Following these instructions on that page to install on a Puppet Inc.-provisioned Mojave MacBook Pro with Puppet agent 4.10.2: If you don't have the yard gem installed yet, install it by running gem install yard Install the puppet-strings gem by running gem install puppet-strings results in Puppet being unable to locate the puppet agent command: garrettottesmbp:Downloads gguillotte$ gem install yard Fetching: yard-0.9.19.gem (100%) -------------------------------------------------------------------------------- As of YARD v0.9.2:   RubyGems "--document=yri,yard" hooks are now supported. You can auto-configure YARD to automatically build the yri index for installed gems by typing:   $ yard config --gem-install-yri   See `yard config --help` for more information on RubyGems install hooks.   You can also add the following to your .gemspec to have YARD document your gem on install:   spec.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs.   -------------------------------------------------------------------------------- Successfully installed yard-0.9.19 Parsing documentation for yard-0.9.19 Installing ri documentation for yard-0.9.19 Done installing documentation for yard after 2 seconds 1 gem installed   garrettottesmbp:Downloads gguillotte$ gem install puppet-strings Fetching: rgen-0.8.2.gem (100%) Successfully installed rgen-0.8.2 Fetching: puppet-strings-2.2.0.gem (100%) Successfully installed puppet-strings-2.2.0 Parsing documentation for rgen-0.8.2 Installing ri documentation for rgen-0.8.2 Parsing documentation for puppet-strings-2.2.0 Installing ri documentation for puppet-strings-2.2.0 Done installing documentation for rgen, puppet-strings after 2 seconds 2 gems installed   garrettottesmbp:Downloads gguillotte$ puppet strings Error: Unknown Puppet subcommand 'strings' See 'puppet help' for help on available puppet subcommands garrettottesmbp:Downloads gguillotte$ puppet-strings -bash: puppet-strings: command not found   garrettottesmbp:ntp gguillotte$ sudo puppet strings Error: Unknown Puppet subcommand 'strings' See 'puppet help' for help on available puppet subcommands The gem is installed to my rbenv home gem directory: puppet-strings (2.2.0) Author: Puppet Inc. Homepage: https://github.com/puppetlabs/puppet-strings License: Apache-2.0 Installed at: /Users/gguillotte/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0   Puppet documentation via YARD but the same behavior occurs without rbenv. Workaround Installing the gem using Puppet's vendored binary as root works: garrettottesmbp:ntp gguillotte$ sudo /opt/puppetlabs/puppet/bin/gem install puppet-strings Password: Fetching: yard-0.9.19.gem (100%) -------------------------------------------------------------------------------- As of YARD v0.9.2:   RubyGems "--document=yri,yard" hooks are now supported. You can auto-configure YARD to automatically build the yri index for installed gems by typing:   $ yard config --gem-install-yri   See `yard config --help` for more information on RubyGems install hooks.   You can also add the following to your .gemspec to have YARD document your gem on install:   spec.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs.   -------------------------------------------------------------------------------- Successfully installed yard-0.9.19 Fetching: rgen-0.8.2.gem (100%) Successfully installed rgen-0.8.2 Fetching: puppet-strings-2.2.0.gem (100%) Successfully installed puppet-strings-2.2.0 Parsing documentation for puppet-strings-2.2.0 Installing ri documentation for puppet-strings-2.2.0 Parsing documentation for rgen-0.8.2 Installing ri documentation for rgen-0.8.2 Parsing documentation for yard-0.9.19 Installing ri documentation for yard-0.9.19 Done installing documentation for puppet-strings, rgen, yard after 16 seconds 3 gems installed   garrettottesmbp:ntp gguillotte$ pwd /Users/gguillotte/.puppetlabs/etc/code/modules/ntp   garrettottesmbp:ntp gguillotte$ puppet strings Files: 4 Modules: 0 ( 0 undocumented) Classes: 0 ( 0 undocumented) Constants: 0 ( 0 undocumented) Attributes: 0 ( 0 undocumented) Methods: 0 ( 0 undocumented) Puppet Classes: 4 ( 0 undocumented) Puppet Defined Types: 0 ( 0 undocumented) Puppet Types: 0 ( 0 undocumented) Puppet Providers: 0 ( 0 undocumented) Puppet Functions: 0 ( 0 undocumented) Puppet Tasks: 0 ( 0 undocumented) 100.00% documented Suggested improvement Either: Strings developers help update the installation documentation, or the installation docs move back to the Strings GitHub repository so open source contributors can maintain them. (It's unclear which development team owns Strings now. PDOC and Strings are not listed on https://confluence.puppetlabs.com/display/ENG/Maintenance .) or The Strings docs are removed in favor of using PDK. pdk build generates the module documentation. Add Comment

This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93)

[Garrett Guillotte (JIRA)]

Garrett Guillotte updated an issue

Puppet Strings / PDOC-279 "puppet strings" command unavailable after following installation docs

Change By: Garrett Guillotte *Problem statement*

Following the instructions at https://puppet.com/docs/puppet/6.4/puppet_strings.html does not result in a functional {{puppet strings}} command. Users following this documentation cannot use {{puppet strings}} to generate module documentation.

*Expected result*

Either following the documented installation instructions works, or if installing and invoking {{puppet strings}} directly is no longer recommended, we point users to PDK or whatever the preferred module docs generation method is now.

*Observed result*

Following these instructions on that page to install on a Puppet Inc.-provisioned Mojave MacBook Pro with Puppet agent 4.10.2:

{quote} - If you don't have the yard gem installed yet, install it by running {{gem install yard}} - Install the puppet-strings gem by running {{gem install puppet-strings}} {quote}

results in Puppet being unable to locate the {{puppet agent}} command:

{code}

{code}

The gem is installed to my rbenv home gem directory:

{code}

puppet-strings (2.2.0)     Author: Puppet Inc.     Homepage: https://github.com/puppetlabs/puppet-strings     License: Apache-2.0     Installed at: /Users/gguillotte/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0     Puppet documentation via YARD

{code} but the same behavior occurs without {{rbenv}}. *Workaround*

Installing the gem using Puppet's vendored binary as root works:

{code}

{code} *Suggested improvement* Either: * Strings developers help update the installation documentation , or the installation docs move back to the Strings GitHub repository so open source contributors can maintain them . ( It's unclear which development team owns Strings now. PDOC and Strings are not listed on [ https://confluence.puppetlabs.com/display/ENG/Maintenance ] . ) or * The installation docs move back to the Strings GitHub repository so open source contributors can maintain them. or * The Strings docs are removed in favor of using PDK. {{pdk build}} generates the module documentation.

Add Comment

[Garrett Guillotte (JIRA)]

* Strings developers help update the installation documentation. It's unclear which development team owns Strings now. PDOC and Strings are not listed on [https://confluence.puppetlabs.com/display/ENG/Maintenance]. or

* The installation docs move back to the Strings GitHub repository so open source contributors can maintain them. or

* The Strings docs are removed in favor of using PDK . , and {{pdk build}} generates is both capable of building the module documentation and is documented as doing so .

Add Comment

[Garrett Guillotte (JIRA)]

* Strings developers help update the installation documentation. It's unclear which development team owns Strings now. PDOC and Strings are not listed on [https://confluence as a Coremunity team project . puppetlabs.com/display/ENG/Maintenance].

or * The installation docs move back to the Strings GitHub repository so open source contributors can maintain them. or

* The Strings docs are removed in favor of using PDK, and {{pdk build}} is both capable of building the module documentation and is documented as doing so.

Add Comment

[Josh Cooper (JIRA)]

Josh Cooper updated an issue

Puppet Strings / PDOC-279 "puppet strings" command unavailable after following installation docs

Change By: Josh Cooper Team: Coremunity Data Platform

Add Comment

[Josh Cooper (JIRA)]

Josh Cooper updated an issue

Puppet Strings / PDOC-279 "puppet strings" command unavailable after following installation docs

Change By: Josh Cooper Team: Data Platform Puppet Developer Experience

Add Comment

[Jean Bond (JIRA)]

Jean Bond updated an issue

Puppet Strings / PDOC-279 "puppet strings" command unavailable after following installation docs

Change By: Jean Bond Comment: A comment with security level 'Developers' was removed.

Add Comment