The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

Feature #6962

self-documenting strings, actions, and options

Added by Anonymous over 3 years ago. Updated over 1 year ago.

Status:ClosedStart date:04/04/2011
Priority:NormalDue date:
Assignee:Nick Fagerlund% Done:

0%

Category:Faces
Target version:2.7.0
Affected Puppet version:development Branch:https://github.com/nfagerlund/puppet/tree/ticket/2.7.x/6962
Keywords: customer

We've Moved!

Ticket tracking is now hosted in JIRA: https://tickets.puppetlabs.com

This issue is currently not available for export. If you are experiencing the issue described below, please file a new ticket in JIRA. Once a new ticket has been created, please add a link to it that points back to this Redmine ticket.


Description

We want to have strings, actions, and options as self-documenting as possible.

This requires:

  • We can declare the documentation inline when creating the various objects in the system.
  • We can introspect the various bits and extract that documentation.
  • We expose this through a ‘help’ string that returns the structured data to allow generic renderings of that information. (eg: to a string for user presentation, or HTML, or whatever else we want based on the outside interface.)
  • We need to implement generic CLI interface that uses the help string to render the help to a string and present that to the user.
  • We need to implement a global option --help for all CLI strings that redirects from the requested string to the help string, and presents help to the user for the string they requested.

Related issues

Related to Puppet - Bug #7086: Faces help needs to support --help arguments Accepted 04/13/2011

History

#1 Updated by Anonymous over 3 years ago

We have this almost complete: the --help argument doesn’t work in all positions correctly, but does work in most of them. Everything else, including most global help delegating to the help face, is now working correctly.

Outstanding: * puppet ${face} --help and puppet ${face} --help ${action} * puppet help ${face} ${action}, by way of a default action for help

#2 Updated by Anonymous over 3 years ago

https://github.com/puppetlabs/puppet/commit/40adee4ade3a447a7397a71d76e042091bbbfbff contains the current code.

#3 Updated by Anonymous over 3 years ago

  • Assignee changed from Anonymous to Nick Fagerlund
  • Target version changed from 2.6.8 to 2.7.x
  • Affected Puppet version set to development

The required changes are in next, and the work of finishing layout and inline documentation handed over.

#4 Updated by Anonymous over 3 years ago

Further work on API to support Nick is in my github, https://github.com/daniel-pittman/puppet/commits/bug%2F2.7.x%2F7132-a-summary-with-a-newline-is-accepted

#5 Updated by Anonymous over 3 years ago

https://github.com/puppetlabs/puppet/compare/9adcb19…a594563 extends this in upstream 2.7.x

#6 Updated by Anonymous over 3 years ago

  • Branch set to https://github.com/daniel-pittman/puppet/commits/feature/2.7.x/6962-finish-documentation-api-for-faces

https://github.com/daniel-pittman/puppet/commits/feature/2.7.x/6962-finish-documentation-api-for-faces has a mostly complete implementation of the documentation API, but needs non-trivial work on the layout and output front. (That said, it does semi-correct ronn(1) output generation for actions right now.)

Additionally, some actual documentation of the faces would be nice, but isn’t done here.

#7 Updated by Anonymous about 3 years ago

https://github.com/puppetlabs/puppet/compare/b7ba66c…b17b49c adds the returns block to actions, which was missed in earlier work, on the 2.7.x branch.

#8 Updated by Nick Fagerlund about 3 years ago

  • Branch changed from https://github.com/daniel-pittman/puppet/commits/feature/2.7.x/6962-finish-documentation-api-for-faces to https://github.com/nfagerlund/puppet/tree/ticket/2.7.x/6962

I’ve reset the branch to point at my documentation string branch. It’s not quiiiite complete, but it’s a decent start.

#9 Updated by Anonymous about 3 years ago

Nick Fagerlund wrote:

I’ve reset the branch to point at my documentation string branch. It’s not quiiiite complete, but it’s a decent start.

This is merged, and will be part of the 2.7.0RC2 release shortly.

#10 Updated by Anonymous about 3 years ago

  • Status changed from Accepted to Closed

This has been replaced by: * #7561: Documentation: help for all Faces * #7562: Documentation: man pages for all Faces * #7563: Templates for Faces documentation

#11 Updated by James Turnbull about 3 years ago

  • Target version changed from 2.7.x to 2.7.0

#12 Updated by Charlie Sharpsteen over 1 year ago

  • Keywords set to customer

Also available in: Atom PDF