As a Masonry user, I want the ability to use a custom formatter

[afeld]

In order to have more control over how output is generated (implementation language, templating system, target-specific logic), we want the formatters in Compliance Masonry to be separate codebases that are called at the right time.

Acceptance Criteria

• There's a way to specify a custom output formatter when invoking compliance-masonry
• There's a "null" formatter that doesn't do much other than just show that custom formatters are possible

Implementation notes

• Have to work out the API/CLI between CM and the formatters
• Lots of refactoring work to pull out related tests, etc.

Original post below.

There's a decent amount of code in Masonry that's specific to docx or gitbook output...thinking it would be great to get that formatter-specific functionality out of Masonry itself. This could mean a plugin-esque architecture, or thinking of Masonry as a library and making it easy to create wrapper CLIs that are more specific to the use case. Thinking of the fedramp-templater specifically, where some FedRAMP, where the "simple" docx templating might not be sufficient.

[joshuamckenty]

GitBook itself has a “formatter” plugin architecture, and the ability to generate a number of different output formats. Any reason we wouldn’t put this in there?

On Jun 7, 2016, at 4:50 PM, Aidan Feldman notifications@github.com wrote:

There's a decent amount of code in Masonry that's specific to docx or gitbook output...thinking it would be great to get that formatter-specific functionality out of Masonry itself. This could mean a plugin-esque architecture, or thinking of Masonry as a library and making it easy to create wrapper CLIs that are more specific to the use case. Thinking of the fedramp-templater specifically, where some FedRAMP, where the "simple" docx templating might not be sufficient.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[geramirez]

I definitely like the idea of distributing masonry's functionality as the project grows. Just to throw another thought in the mix; the cf cli has a great way of allowing plugins.

[afeld]

GitBook itself has a “formatter” plugin architecture

I found https://developer.gitbook.com/plugins/index.html, but am not seeing anything about adding output formats...have any links?

Any reason we wouldn’t put this in there?

If it works, fine by me!

the cf cli has a great way of allowing plugins

Was just going to ask if that functionality is reusable/extractable, but a quick search brought up a few packages that are designed for just that:

http://stackoverflow.com/a/37692475/358804

Sounds like a good way to go to me!

[pburkholder]

I'm not sure how I feel about this. The current compliance-masonry workflow is hard enough to follow, and has enough inconsistencies, that adding another layer of abstraction with plugins feels premature.

My gut says I'd like to see consistent generation of content for gitbook serve and gitbook pdf with the current flow before adding in a plugin architecture. My gut has an open mind though.

[afeld]

The reason I bring it up is because we are going to need more and more FedRAMP docx-specific logic, which doesn't seem right to put in Masonry directly. Maybe we leave the gitbook logic in Masonry since that's the default workflow?

[pburkholder]

Hi - I see 'in progress' here. Does that mean work is underway in this repo, or as a separate project? Given recent discussion it seemed that the token substitution approach as discussed in the README is not keeping up with real pace of change, so what approaches are under consideration?
Thanks, Peter

[afeld]

Sorry, "in progress" meant I had started reaching out for advice, doing research, and jotting down ideas about various plugin architectures...not that any code was being written yet. I have some open questions:

• Do we care about supporting plugins in any language? @joshuamckenty mentioned wanting to use Jinja2 templates, for example.
• How does data travel between the plugin and Masonry?
• Does Masonry need to be made aware of the plugins?

(Note that I'm using "plugin" and "formatter" interchangeably for now.) After mentally wrestling with these for a bit, I came to the following conclusions:

• We don't really know everything we could want plugins to do, and building around that unknown is hard.
• Supporting formatters in different languages from Masonry would be hard, since you can't rely on RPC conveniences/packages/conventions in Go mentioned above.
• With an increasingly formalized schema and fairly stable opencontrols/ directory structure, writing a formatter that reads from those files directly wouldn't be that much harder than getting data through Masonry.

In the spirit of getting something working quickly, I'm going to try using Masonry as a library for opencontrol/fedramp-templater#18, so no/minial code changes should be required to Masonry itself. In other words, I'm punting on the plugin idea for now, trying to achieve the same outcome in a different way.

[afeld]

Closing for now, since using Masonry as a library has been working well (#202 and linked issues will make this even easier). We can revisit later if there's demand.