Abstract the template engine

[KittyGiraudel]

Possibly not forcing Swig. In any case, making the view more configurable.

[KittyGiraudel]

Related: #69.

[valeriangalliat]

I like the idea. Basically, a theme would have a dependency with its template engine, but SassDoc wouldn't force any.

This comes handy with the idea of theme inheritance. sassdoc-theme-default would rely on Swig for example, to provide an universal views structure easily overridable, and sassdoc-theme-dark would require sassdoc-theme-default to extend it.

The index.js of a theme would export a render function taking an object as parameter.

var theme = require('sassdoc-theme-dark');

theme.render({
  // Usual SassDoc view variables here
  ...

  // Any other theme-specific variables
  layout: theme.LAYOUT_TWO_COLUMNS,
});

I don't know if this should return an HTML string (can take a lot of memory if the project is big), or if we need to pass it a destination file path to write in, or maybe a destination directory to allow a theme to create multiple files (other than the conventional assets folder that would always be copied in SassDoc's destination directory).

[valeriangalliat]

After some reflection, the templating module can be abstracted at a point it's not bound to SassDoc in any way. I think it can live in its own repo and Node module.

And while I'm thinking about it, I just saw something similar yesterday; Json Resume is a project where you have a JSON input (like SassDoc's main object passed to the view), with a theming system that looks exactly like what we need.

All themes are simply NPM modules that are named as jsonresume-theme-{{themeName}}

They are expected to take a resume.json as an input and simply to return a HTML output.

[KittyGiraudel]

I think it can live in its own repo and Node module.

I like that.

And while I'm thinking about it, I just saw something similar yesterday; Json Resume is a project where you have a JSON input (like SassDoc's main object passed to the view), with a theming system that looks exactly like what we need.

I like that even better.

[pascalduez]

Oh yeah, JSON resume is a great example. Like that project. +1 for being able to just pass the whole object to the theme.

[valeriangalliat]

I took a look at Json Resume's theme manager, I think there's not enough abstraction for our needs.

It's still really interesting to see how it works for inspiration, but I have some doubts:

• The render method of a theme package takes an object as parameter and returns the HTML output.

  While it's a simple interface, I'm not sure about it. I don't like to work with the whole HTML file in memory, and we can't extend it to dump multiple HTML files in a destination directory instead of a single file.

  I would see something more like:

  theme.render(viewData, destinationDirectory);

• The actual code supposed to use themes don't support custom themes required via npm for now.

I'll create a new project for the theming engine tonight.

[valeriangalliat]

I started to work on this in this repository https://github.com/valeriangalliat/themeleon-test. I'm not sure about the name though, but this is not my priority.

My ideas are in the readme, and I've provided a simple implementation using this test theme.

The code is actually dead simple. The {{ stuff_to_theme }}-theme-{{ theme_name }} package have an index.js that exposes directly a function taking:

1. the destination directory,
2. the context data (passed to the template,

... and returns a Promise/A+ compliant instance.

Any program that wants to use the theme can require it and call the function.

If you ask me, I choosed to place the destination directory before the context so it can easily be currified. I mean that you could have a renderThere function already bound to the destination directory, and you could call it directly with the context.

Like I say in the readme, I'm planning to create an helper package for the themes, so they don't need to take care of the promises stuff, and "low-level" filesystem calls.

[FWeinb]

How far are we on this?

[valeriangalliat]

I didn't have a lot of time to work on it this week, but I've managed to do this yesterday: https://github.com/valeriangalliat/themeleon.

There's no actual example other than the one in the readme, but I plan to do it this week-end. At first, only Swig will be supported as template engine plugin, but it will be easy to support any other template engine.

[FWeinb]

We should not make any assumptions about the template engine.

[valeriangalliat]

Yes, I'm just adding Swig at first for testing purpose, but the template engine is a dependency of the final theme, not of the theme engine.

[KittyGiraudel]

Moving this to 1.2. Val and I are on fire.

[FWeinb]

I just want to make something clear. The only thing SassDoc should expect from a template is that it exports a function like this:

module.exports = function(dest, context, options){
}

Everything else should be an implementation detail of the template. What you are doing with Themeleon sounds way to complicated. Just let the author of the template choose how he wants to implement it.

[KittyGiraudel]

On the other hand, Themeleon is kind of a framework to build themes, so perhaps it's a good idea. I really don't know guys, I'll leave this up to you.

[FWeinb]

Yeah, if an author wants to use Themeleon he can. But don't make it the only way to create themes for SassDoc

[valeriangalliat]

Themeleon only hides the "low-level" filesystem operations from the theme creator, leaving him with only simple functions like t.copy(src, dest), t.swig(src, dest), only giving relative paths to the theme directory and render directory (these are resolved automatically).

Themeleon is actually very lightweight (86 SLOC including themeleon and themeleon-swig).

But it's not at all a requirement. The only interface needed is:

/**
 * @param {string} dest Directory to render theme in.
 * @param {object} ctx Variables to pass to the theme.
 * @return {promise} A Promises/A+ implementation.
 */
module.exports = function (dest, ctx) {};

Themeleon is built around this interface, and make it trivial to build a theme, but anything implementing this interface will work.

And to make it clear, Themeleon is not a dependency of sassdoc in any way. It's at most a dependency of sassdoc-theme-{light,dark}, only because we find it more convenient to implement the interface than raw fs and swig calls.

[FWeinb]

Okay. We should document it exactly like this.

[valeriangalliat]

Nice! I'll merge sassdoc/themeleon into sassdoc/develop since the theme abstraction is functional.

[FWeinb]

Awesome!