Guide Code blocks are sometimes empty

[mickmcgrath13]

I noticed this in the chat guide, but it is likely not even a canjs issue. Creating it here just to get a discussion started.

Steps to reproduce:

• Load http://v3.canjs.com/doc/guides/chat.html
• Click a link from the TOC (I have been clicking "List Messages")
• Click the browser's back button
• scroll down

You should see something like this:

It should look like this:

[justinbmeyer]

@mickmcgrath13 I just tried this. I did not see the error. Does this always happen for you? What is your browser version?

[mickmcgrath13]

So, it turns out that Google code prettify actually works in batches so as to not block the browser for too long. Unfortunately, the length of time for a batch to be allowed to run seems hardcoded into the code at 250 ms, and the same is true for the time to wait.
See here and here.

I can think of a couple ways to resolve this

Option 1 - Turn off batching

Solution

There is an option on the window that can be set to disable the async/batch feature:

/**
 * Split {@code prettyPrint} into multiple timeouts so as not to interfere with
 * UI events.
 * If set to {@code false}, {@code prettyPrint()} is synchronous.
 */
window['PR_SHOULD_USE_CONTINUATION'] = true;

Notes

I think this would be sufficient, but it would potentially slow down the page for bigger jobs.

Option 2 - Use prettyPrint's done callback

Solution

The prettyPrint method takes a couple of parameters, the first of which is a function to be executed when the prettifying is complete. (See here).

Where we call the prettyPrint method, we could provide a return value of a Deferred which is resolved within prettyPrint's done callback:

    require('./prettify-engine');
    require('./prettify.less');
    var $ = require('jquery');
    module.exports = function () {
        var doneDeferred = $.Deferred();
        var codes = document.getElementsByTagName('code');
        for (var i = 0; i < codes.length; i++) {
            var code = codes[i];
            if (code.parentNode.nodeName.toUpperCase() === 'PRE') {
                code.className = code.className + ' prettyprint';
            }
        }
        prettyPrint(function(){
            doneDeferred.resolve();
        });

        return doneDeferred;
    };

Then where we loop over the packages, we look for a deferred (has .then) and wait for that to resolve before proceeding.

                function processPackages(packageIndex, callback){
                    var i = packageIndex || 0,
                        packageNames = Object.keys(window.PACKAGES),
                        packageName, packageResult;

                    if(i === packageNames.length){
                        if(typeof callback === 'function'){
                            callback();
                        }
                        return;
                    }

                    packageName = packageNames[i];
                    if (typeof window.PACKAGES[packageName] === 'function') {
                        packageResult = window.PACKAGES[packageName]();
                        if(packageResult && packageResult.then){
                            packageResult.then(function(){
                                processPackages(i+1, callback);
                            });
                        }else{
                            processPackages(i+1, callback);
                        }
                    }else{
                        processPackages(i+1, callback);
                    }
                };

                // go through every package and re-init
                processPackages(0, function(){
                    init();
                    setDocTitle();
                });

Notes.

This solution would allow non-docs related scripts to do their thing.

[justinbmeyer]

do sync for now. Open an issue in bit-docs-generate-html to eventually handle promises.

[mickmcgrath13]

@justinbmeyer, should it be bit-docs-generate-html or bit-docs-html-canjs ?

The code I have above was in bit-docs-html-canjs.