Comments (19)
Related: #69.
from sassdoc.
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).
from sassdoc.
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.
from sassdoc.
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.
from sassdoc.
Oh yeah, JSON resume is a great example. Like that project.
+1 for being able to just pass the whole object to the theme.
from sassdoc.
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.
from sassdoc.
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:
- the destination directory,
- 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.
from sassdoc.
How far are we on this?
from sassdoc.
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.
from sassdoc.
We should not make any assumptions about the template engine.
from sassdoc.
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.
from sassdoc.
Moving this to 1.2. Val and I are on fire.
from sassdoc.
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.
from sassdoc.
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.
from sassdoc.
Yeah, if an author wants to use Themeleon he can. But don't make it the only way to create themes for SassDoc
from sassdoc.
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.
from sassdoc.
Okay. We should document it exactly like this.
from sassdoc.
Nice! I'll merge sassdoc/themeleon
into sassdoc/develop
since the theme abstraction is functional.
from sassdoc.
Awesome!
from sassdoc.
Related Issues (20)
- Security vulnerability via update-notifier dependency HOT 2
- Support documentation for css custom properties HOT 1
- Maintenance Status HOT 1
- "verbose" and "strict" parameters are ignored if defined within configuration
- SASS files correctly parsed but the documentation is not generated HOT 4
- feature request (?): link to image HOT 2
- Screen overflow on mobile
- `@see` doesn't recognize sass module references
- Warning for Annotation `property` when it is not being used
- Allow more than one @output HOT 1
- [ERROR] Could not find any executable for "sass-convert". Operation Aborted. HOT 3
- Keywords feature
- [WARNING] Parser for annotation `flag` not found. Location: `linePoster.test.scss:5:8` HOT 1
- Interested in TypeScript definitions? HOT 2
- esm support
- Remove vulnerable `update-notifier` dependency
- Update the version of jQuery used in the built docs
- How to document @function that takes parameter a map key.
- Deprecation warning for core-js when installing sassdoc. Upgrade needed.
- Overrides the editor.definitionLinkOpensInPeek setting. HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from sassdoc.