search

SassDoc / sassdoc-theme-default

Default theme for SassDoc.
MIT License
10 stars 30 forks source link

Swig migration #96

Closed pascalduez closed 5 years ago

pascalduez commented 7 years ago

So apparently Swig is deprecated and not maintained anymore, hence a nice warn in the shell while installing SassDoc.

I guess we should migrate to another engine. Nunjucks is great and pretty close to Swig syntaxically.

KittyGiraudel commented 7 years ago

Yes. Helpful: https://medium.com/engineers-optimizely/js-templating-transitioning-from-swig-to-nunjucks-ac0e94d1794b#.t6swn4o4e.

valeriangalliat commented 7 years ago

👍

DanielRuf commented 6 years ago

Also there are two CVEs in a peer dependency of swig, uglify-js. https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-8857 https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-8858

DanielRuf commented 6 years ago

https://www.npmjs.com/package/swig-templates as fast replacement or handlebars (which is the best solution imo).

LeaveAirykson commented 6 years ago

any update on this?

reneroth commented 5 years ago

I would be willing to work on this…

…provided we reach a decision on what templating engine to use 🤔

pascalduez commented 5 years ago

The SassDoc team was in favor of Nunjucks. It's a really good engine, and also close to Swig in syntax and features. So this might limit the changes required.

See themes already built with it:
https://github.com/pascalduez/sassdoc-theme-literate
https://github.com/oddbird/sassdoc-theme-herman

renatodeleao commented 5 years ago

Also landed here due the security issue. I can also give hand on this, don't see any open PR for this and the ones open are stalled. What's the status on this? help wanted?

Cheers!

DanielRuf commented 5 years ago

Also landed here due the security issue. I can also give hand on this, don't see any open PR for this and the ones open are stalled. What's the status on this? help wanted?

Hi. Would be great if you could help here =) Unfortunately I found no time until now to refactor / change the affected parts.

pascalduez commented 5 years ago

@renatodeleao Yes, help welcome!

From Swig to Nunjukcs it shouldn't be a giganormous task hopefully.

renatodeleao commented 5 years ago

@pascalduez @DanielRuf alright i'll give it a try.

It will be good for me as I just started with sassdoc last week (unfortunately) and I'm not acquainted with the theming system neither the dev process, but will be good to learn. Learning nunjucks is also a bonus (a priori looks like pretty straightforward migration).

Hopefully this project can also benefit from my unbiased beginners' mind feedback and i'll make an effort to document the pain points along the way and will report them on the hopefully successful incoming PR.

One thing that I can't promise is a delivery date, as it will depend on my FT job stress/availability, but i'll try to be quick, as my own library kind-of-depends on it.

✌️

pascalduez commented 5 years ago

@renatodeleao Great!

I think you can get quite some infos and clues looking at https://github.com/pascalduez/sassdoc-theme-literate, a theme I built with Nunjucks, especially the render phase. Also There should be something to ease the development process in there, some gulp tasks with livereload and stuff.

One thing that I can't promise is a delivery date

No pressure, just enjoy it.

renatodeleao commented 5 years ago

Thanks @pascalduez, i actually did enjoyed :)

I won't lie, it took more time to setup the dev flow and understand data flow/types than to actually replace per nunjucks, which was a smooth migration.

I think we should add minimal dev setup (npm scripts or gulp) and instructions to readme, but let's leave it to another PR. I'll have to leave now, take a look at the PR and i'll try to find time for review necessary updates during the week.

Have a nice weekend!

DanielRuf commented 5 years ago

npm scripts or gulp

I would recommend pure npm scripts as gulp and others are painful wrappers imo.

pascalduez commented 5 years ago

@renatodeleao Thanks!

I think we should add minimal dev setup (npm scripts or gulp) and instructions to readme

Agree! That's what I envisioned with https://github.com/pascalduez/sassdoc-utils but it's far from ready/complete. Also already a bit outdated (deps).

I would recommend pure npm scripts as gulp and others are painful wrappers imo.

Agree too. If possible. Fact is SassDoc core make great use of streams and the Vinyl file format (Gulp), so it naturally integrates very well with Gulp. But the simpler, the better.

pascalduez commented 5 years ago

sassdoc-theme-default@2.8.1
sassdoc@2.7.0