Add a mechanism to register handlebars helpers to the engine used by selleck #9

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
3 participants
@gotwarlost

Do not actually merge this - just a proof of concept for your review and feedback.

ananthk
Add --handlebars (bad name for now) option to be able to register han…
…dlebars helpers to be used for doc generation
@gotwarlost

This comment has been minimized.

Show comment Hide comment
@gotwarlost

gotwarlost Dec 16, 2012

The intent behind this change to be able to generate standard pieces of documentation using component.json metadata.

My immediate use case is that I want to document some sample JSON configuration - so what I did was to set up that JSON sample in component.json and use a helper to render it into the docs.

This way I can be assured that there are no typos in the JSON since it is guaranteed to be well-formed.

There are other use cases I can think of like custom sorting of objects in the component config to generate docs in a predictable order.

The intent behind this change to be able to generate standard pieces of documentation using component.json metadata.

My immediate use case is that I want to document some sample JSON configuration - so what I did was to set up that JSON sample in component.json and use a helper to render it into the docs.

This way I can be assured that there are no typos in the JSON since it is guaranteed to be well-formed.

There are other use cases I can think of like custom sorting of objects in the component config to generate docs in a predictable order.

@rgrove

This comment has been minimized.

Show comment Hide comment
@rgrove

rgrove Dec 17, 2012

This is a good idea, and it's something Selleck definitely needs.

I think this would be better implemented as an option in component.json and project.json though, rather than a command line option. That way the project or component defines what its helpers are rather than whoever happens to run Selleck on the command line.

rgrove commented Dec 17, 2012

This is a good idea, and it's something Selleck definitely needs.

I think this would be better implemented as an option in component.json and project.json though, rather than a command line option. That way the project or component defines what its helpers are rather than whoever happens to run Selleck on the command line.

@davglass

This comment has been minimized.

Show comment Hide comment
@davglass

davglass Dec 17, 2012

Owner

Yeah, about like how YUIDoc handles it..

Owner

davglass commented Dec 17, 2012

Yeah, about like how YUIDoc handles it..

@gotwarlost

This comment has been minimized.

Show comment Hide comment
@gotwarlost

gotwarlost Dec 17, 2012

Sounds good to me. One point i have though is that the Handlebars object is a singleton and I wonder how you would scope specific helpers to the context in which they should be sandboxed.

Also, it would be nice if the --server mode did not require a restart when these helpers change.

Sounds good to me. One point i have though is that the Handlebars object is a singleton and I wonder how you would scope specific helpers to the context in which they should be sandboxed.

Also, it would be nice if the --server mode did not require a restart when these helpers change.

@rgrove

This comment has been minimized.

Show comment Hide comment
@rgrove

rgrove Dec 17, 2012

Yeah, the global helper registration is an unfortunate limitation of Handlebars. But in Selleck's case at least, I don't think it's a big problem, as long as people are careful to avoid helper name collisions.

In --server mode, Selleck could monitor the helper files for changes. When it detects a change, it just needs to reload the file and re-register the helpers.

rgrove commented Dec 17, 2012

Yeah, the global helper registration is an unfortunate limitation of Handlebars. But in Selleck's case at least, I don't think it's a big problem, as long as people are careful to avoid helper name collisions.

In --server mode, Selleck could monitor the helper files for changes. When it detects a change, it just needs to reload the file and re-register the helpers.

@gotwarlost

This comment has been minimized.

Show comment Hide comment
@gotwarlost

gotwarlost Jan 26, 2013

Closing this PR and will open one with @rgrove 's suggested implementation

Closing this PR and will open one with @rgrove 's suggested implementation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment