Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Plugins #121

Merged
merged 4 commits into from Jul 22, 2014

Conversation

Projects
None yet
3 participants
@jdcantrell
Copy link
Contributor

commented May 28, 2014

This implements a simple plugin interface for hologram.

Plugins can be listed in the config yml like:

plugins:
 - my_plugin.rb
 - your_plugin.rb

Hologram will call these plugins in four cases:

  1. .initialize(config, args) - config is the yml config hologram is using, args are the arguments passed in from the command line
  2. Just after a doc_block has been created: .block(comment_block, file_name, has_plugin)
  3. .plugin(plugin_data, comment_block, filename)
  4. And after all comments have been processed: plugin.finalize(pages)

Each plugin class is created as a new instance so that it can store whatever internal state desired. comment_block is mutable, so changes a plugin makes to comment_block's values will be reflected in the documentation.

When extending from the Hologram::Plugin plugins can also easily define blocks within the documentation:

[[[plugin:css-test
<ul class="inline-list">
  <li>I
  <li>Am
  <li>Inline
</ul>
]]]

The return value of .plugin will be used to replace the plugin block. When the plugin is not active and empty string is used to replace the block.

@jdcantrell

This comment has been minimized.

Copy link
Contributor Author

commented May 28, 2014

begin
opt.parse!(args)
rescue OptionParser::InvalidOption => e
extra_args.push(e.to_s.sub(/invalid option:\s+/, ''))

This comment has been minimized.

Copy link
@aflanagan

aflanagan Jun 4, 2014

Collaborator

not sure I totally follow the extra_args is it flags that would be passed to a plugin? If so, how are they specified?

This comment has been minimized.

Copy link
@jdcantrell

jdcantrell Jun 4, 2014

Author Contributor

extra_args will be passed to the plugins. Right now I use this to search for --test to know if I should generate the test files or not in the css critic plugin.

Not entirely crazy about this, but it will probably be nice to talk to plugins via command line in some cases.

This comment has been minimized.

Copy link
@aflanagan

aflanagan Jun 4, 2014

Collaborator

hmmm...i think if we need to pass commands to plugins we might want to consider a specific syntax for it. Maybe something like

--plugins:myplugin:test::yourplugin:foo

then maybe we could even avoid passing extra_args around and just set those options somewhere that would be accessible from the plugins class. Thoughts?

EDIT: that separation scheme could probably use a bit of work, but something like that...

This comment has been minimized.

Copy link
@jdcantrell

jdcantrell Jun 4, 2014

Author Contributor

A plugin can do that if it wants to, and it is probably a good practice in case hologram adds a new flag. I don't think we need to enforce anything specificly for it though since all plugins will likely be unmaintained by the hologram project.

This comment has been minimized.

Copy link
@aflanagan

aflanagan Jun 4, 2014

Collaborator

yeah, fair enough. i guess it's unlikely that there will be a robust ecosystem of plugins, and that people would be using more than one or two at a time.

@aflanagan

This comment has been minimized.

Copy link
Collaborator

commented Jun 4, 2014

Ok, so the idea is that you have some plugin Foo, and there are a couple of possibilities for what you might want to process with that plugin. You might want to do something with a doc_block object, or you might want to do something with the hologram output, pages

So, when you write your plugin you can define one or both of those methods and it will be called when a doc_block is created, and when we have the final pages output ready for rendering.

If so, I would propose changing the names to something like on_doc_block_create and on_output_finalized. Those might be a little to verbose, but maybe they convey the intent a little better.

I'm not sure I have an immediate need/desire to write a plugin, but your CSS Critic is pretty interesting, and I like the flexibility that it adds. Let me mull it over a little more and see if I have anything else to add.

@jdcantrell

This comment has been minimized.

Copy link
Contributor Author

commented Jun 23, 2014

on_block_create and on_output_finalized make me sad though :(

@jdcantrell

This comment has been minimized.

Copy link
Contributor Author

commented Jun 26, 2014

Some other tasks:

  • Ignoring this for now: Allow plugin to get access to entire file, allow it to get access to source between blocks
  • DONE: Create a plugin specific tag something like [[[test ]]] and make it easy for plugins to create and read these new tags in the markdown. Default renderer would strip out these sections (makes it so that if some hologram library has tags for a plugin but you don't use that plugin your style guide won't get extra text added)

JD Cantrell and others added some commits May 28, 2014

Add plugin class
Add Hologram::Plugin that other plugins can extend from. This takes
takes care of the following cases:

- Checks arguments to see if the plugin is active (is_active? = true)
- Replaces plugin text when disabled
- Plugins get their text from [[[plugin:plugin-name ... ]]] blocks. This
is done automatically by the base plugin class. The .plugin method can
return either an emtpy string or some other text that will be put in the
plugin block's place.

jdcantrell added a commit that referenced this pull request Jul 22, 2014

@jdcantrell jdcantrell merged commit 3dd6559 into trulia:master Jul 22, 2014

1 check failed

continuous-integration/travis-ci The Travis CI build could not complete due to an error
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.