Feature #6962
self-documenting strings, actions, and options
| Status: | Closed | Start date: | 04/04/2011 | |
|---|---|---|---|---|
| Priority: | Normal | Due 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: | ||||
| Votes: | 0 |
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
--helpfor 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
History
Updated by Daniel Pittman about 1 year 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
Updated by Daniel Pittman about 1 year ago
https://github.com/puppetlabs/puppet/commit/40adee4ade3a447a7397a71d76e042091bbbfbff contains the current code.
Updated by Daniel Pittman about 1 year ago
- Assignee changed from Daniel Pittman 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.
Updated by Daniel Pittman about 1 year 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
Updated by Daniel Pittman about 1 year ago
https://github.com/puppetlabs/puppet/compare/9adcb19…a594563 extends this in upstream 2.7.x
Updated by Daniel Pittman about 1 year 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.
Updated by Daniel Pittman about 1 year 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.
Updated by Nick Fagerlund about 1 year 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.
Updated by Daniel Pittman about 1 year 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.
Updated by Randall Hansen about 1 year ago
- Status changed from Accepted to Closed
Updated by James Turnbull 11 months ago
- Target version changed from 2.7.x to 2.7.0