More flexible theme customization

[sgrishchenko]

Main problem

I am a developer of reselect-utils. I use typedoc for docs generation. My project is written on Typesript, but I wanted to provide dark theme for my documentation and now half of my codebase is a huge CSS file. I have a some plan to improve it.

Road map

• Migrate from Grunt to webpack - it will allow to bundle TS without namespaces and resolve all static files smarter than just a concatenation.
• Change theme API - now API of this library is collection of template files and two static files (CSS and JS). I propose to expose unbudled TS and SASS files as addition to HBS templates to allow override any part of theme (not only markup). Also I propose to expose some build function, that can receive all theme parts from user and build HTML, CSS and JS from HBS, SASS and TS. It can look like this:

const webpack = require('webpack');

export function buildTheme() {
    return new Promise((resolve, reject) => {
        webpack(webpackConfig, (err, stats) => {
            if (err) {
                return reject(err)
            }
            if (stats.hasErrors()) {
                return reject(new Error(stats.compilation.errors.join('\n')))
            }
            resolve()
        })
    })
}

So, what do you think about that? Will it be useful and helpful?

[Gerrit0]

Sorry for the delay in response here, the themes repo is always the last thing I look at & is thus the most likely to be missed over a weekend or two...

Switching to a modules - whether this is Webpack, or some other tool I don't much care... I like this a lot. I do have questions about how much of the current JS is necessary.

1. Search - needs JS.
2. Filtering (visibility/inherited) - needs JS.
3. Overload switching - I'm not convinced this makes the display better. Almost every other doc tool that I see simply displays them one after another... with a lot of overloads, TypeDoc's current implementation is actively bad on mobile.
4. Highlighting the current menu item in the side navigation - meh? Node's docs don't even have a side navigation... for the current page, and I don't find myself missing it... doesn't hurt anything I guess.

Exposing unbundled TS - The dynamic JS functionality is small enough that I already question how useful using TypeScript for it is... I worry about exposing the unbuilt files since it makes nearly any refactoring a breaking change. Exposing SASS - Same concerns about this as exposing TS, also, I think SASS is overkill for what we do. It only takes ~300 lines of CSS to replicate the entire setup in this repo. Considering that SASS is >50% of the build time for this repo...

Exposing a build function is dangerous. We either need to detect whether we need to rebuild due to outside changes (tricky...) or rebuild every time (very slow...)

A dark theme is something I've wanted for a while.... and I've started taking steps to support it natively. The first step of this was switching all colors from using color names/numbers to css variables. This isn't near done yet unfortunately... but some steps have been made. https://github.com/TypeStrong/typedoc/blob/library-mode/static/style.css#L6-L16

[sgrishchenko]

Thank you for answer. I see what you think about TS, but Typedoc is tool for TS documentation. In my opinionion, TS using is very symbolic and principal question for this library. I very like typescript and I believe that it does not add many overhead for development.

But I can't say the same about SASS. I think modern CSS can solve all tasks for this library and I am happy that you will use CSS variables for colors.

But it may not solve my problem. It is not problem for me to write some code in SASS, my problem in that I have to write over 300 lines of code, and every time when I wate to update Typedoc I need to suppors this huge file. To be honest, I have not understand your point about "tricky or very slow" build. May be I am wrong, but now there is not any mechanism like watch-mode, that detects changed theme files automatically and re-builds output. So every time when I need to rebuild theme I just need start cli-command, that rebuild all Handlebars templates every time. I think that if CSS and JS built every time too it would not take much more time.

Anyway, if I find time, I will prepare pull request with ES6 imports instead namespaces. I will try to setup build output without breacking changes (the same files in same folders). Other steps are optional and they can be discaussed again.

[sgrishchenko]

I have sent PR with desribed changes, see #112