Allow custom theming

[KittyGiraudel]

I am well aware the current design of SassDoc won't suit everybody. Actually, no design can convince everybody.

I thing an important feature would be to all the user to use a custom theme. Still, I'm not quite sure what's the best way to handle this.

I'm willing to hear opinions.

[valeriangalliat]

For the end-user, I would see something like this:

npm install sassdoc-theme-foo
sassdoc -t foo ...

SassDoc would comme with sassdoc-theme-default as default, or whatever (default-dark, default-light, etc).

A theme could override the Swig views (so we need a pre-defined and documented base structure for Swig views), and would have its own assets folder. In a view, any relative path to assets/* would point to the theme's assets folder.

A theme could have its own variables defined in view.json, so everything from view.json should be accessible in Swig views.

[KittyGiraudel]

Moving this to 2.0.

[valeriangalliat]

Concerning my previous comment, this is how I think we can implement it:

// `args` from docopt
var themeName = args['--theme'];
var theme;

try {
  theme = require('sassdoc-theme-' + themeName);
} catch (e) {
  // Display error in `stderr` and return exit code 1
}

theme.path; // Path to theme directory (from the Node module)

So a theme would contain only a index.js in the package root, like this:

exports.path = __dirname;

(Or maybe there's a better solution to get a Node module directory?)

The package directory would then contain assets and views directories, and anything else needed by the theme (a makefile with a task to compile Sass in assets directory, lint theme JS or whatever). For example:

sassdoc-theme-foo/
  assets/
    css/
      main.css
    js/
      main.js
  views/
    includes/
      header.html.swig # Will override the original version
  index.js
  package.json

SassDoc would copy theme.path + '/assets' in the destination folder.

For the views, I don't know if we can define a custom file resolver with Swig, but otherwise we can generate a temporary directory, copy all SassDoc's distribution views, then merge them with theme.path + '/views' and render in the destination folder.

[valeriangalliat]

Since the abstraction of the template engine allows to write custom themes, this issue is a duplicate of #47.