Allow custom theming #69

Closed
HugoGiraudel opened this Issue Jul 8, 2014 · 4 comments

Comments

Projects
None yet
2 participants
@HugoGiraudel
Member

HugoGiraudel commented Jul 8, 2014

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.

@HugoGiraudel HugoGiraudel added this to the 1.2 milestone Jul 8, 2014

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 8, 2014

Member

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.

Member

valeriangalliat commented Jul 8, 2014

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.

@HugoGiraudel HugoGiraudel added 2.0 and removed 1.2 labels Jul 8, 2014

@HugoGiraudel HugoGiraudel modified the milestones: 2.0, 1.2 Jul 8, 2014

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 8, 2014

Member

Moving this to 2.0.

Member

HugoGiraudel commented Jul 8, 2014

Moving this to 2.0.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 8, 2014

Member

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.

Member

valeriangalliat commented Jul 8, 2014

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.

@HugoGiraudel HugoGiraudel added 1.3 and removed 1.2 labels Jul 9, 2014

@HugoGiraudel HugoGiraudel modified the milestones: 1.3, 2.0 Jul 9, 2014

@HugoGiraudel HugoGiraudel removed the 2.0 label Jul 9, 2014

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 9, 2014

Member

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

Member

valeriangalliat commented Jul 9, 2014

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

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