Cesium: Consistent boilerplate code in Sandcastle demos

[lilleyse]

Some Sandcastle examples use outdated or inconsistent boilerplate code. This can be fixed be clicking the Save As button in each demo and replacing the code.

This would make a good beginner issue.

More details and an example from @emackey in https://github.com/AnalyticalGraphicsInc/cesium/pull/6337/

The other changes here are just from re-saving the demo directly from a Sandcastle instance. Would be great to have an intern go through and re-save all the demos at some point, so the boilerplate code all matches what Sandcastle produces (or write a build script to do it).

[mramato]

To avoid manual labor in the future, we should be able to automate this process so that we re-save all Sandcastle examples with a single npm command, just like we do with sortRequires. Should be possible with either headless Chrome or Electron.

[srwiseman]

I could probably automate this for you guys. Not sure I totally understand what you mean, though.

Are you saying that there's a mismatch between the code displayed on the sandcastle screen and the code in the actual html files?

[emackey]

@srwiseman Thanks for the offer! The Sandcastle system has a "Save" functionality built-in, and the way it works is a little unorthodox. You can write or modify some Sandcastle code directly in your web browser, testing it with F8 and using the integrated Cesium docs etc., and then when you're done, you click "Save As" from the top toolbar. Sandcastle offers you a button "Save HTML file..." and you end up "downloading" your own code from the client-side-only web page.

But you end up downloading more than just your own code. Sandcastle attaches some boilerplate HTML and JS, called the Sandcastle "Bucket." This means that what you've downloaded is not just a loose snipped of JavaScript, it's a full HTML file with your code embedded in a script tag. The resulting file can be (and should be) saved directly to the Sandcastle gallery folder. The saved HTML can be viewed as a stand-alone page right from there (although it still needs to be hosted, not just read from the filesystem there). The next time you run the Cesium build, it will find the new save and sweep it into the Sandcastle Gallery listing, so it can be loaded back into Sandcastle right from the gallery bar.

Here are some known problems:

• The Sandcastle "Bucket" does change every so often, and when it does, ideally every gallery demo that exists should be updated to the new bucket code. Typically the old ones still load fine, so no one bothers to update them. A manual load-then-save from Sandcastle itself will cause the bucket code to be reset to the current contents.

• Sometimes, well-meaning developers actually try to modify or whitespace-format the saved gallery HTML directly, like in some kind of text editor or other horrible app that isn't official Sandcastle. Savages, I tell you.

So, what's needed is a build script that will run some of the load & save code from Sandcastle. It would, one at a time, import each gallery demo, use the Sandcastle load code to strip away the bucket code that was saved into the demo itself, and then use Sandcastle save code to add a copy of the current bucket back to the loaded demo. The result can then be saved back to the gallery in-place, overwriting the previous version.

With this script, one could make a change to the actual bucket, and then the script would rip through the entire collection of Sandcastle demos and update the bucket code in each of them.

Criteria for success is: I should be able to load any demo from the gallery, click "Save As", and save the demo back over itself, and git should say that nothing has changed. We worked hard to make Sandcastle capable of round-trips with no changes per trip, but it only works when the thing being loaded has the correct bucket code.

[srwiseman]

Gotcha! Thanks for the awesome explanation.

Here's my proposed short-term solution:

I'll go through and manually re-save all of the demos so that they have a consistent boilerplate code. I'll then do something like:

git update-index --assume-unchanged Apps/Sandcastle/gallery/*.html

That way the html files stay tracked, but git won't pick up future changes when you do an add/commit. When someone changes the boilerplate code, they have to do:

git update-index --no-assume-unchanged Apps/Sandcastle/gallery/*.html

Then re-save the html files.

Once that short-term solution is in place, I can work on a longer-term solution in the form of a script that automatically deploys the current boilerplate code to all sandcastle html files.

How does that sound?

[emackey]

I don't think we're pressed for a short-term solution here. The individual demos get updated a lot more frequently than the bucket code, so we don't want developers to mess with git update-index just to update a particular demo.

I think just the long-term solution, in the form of a script that updates the bucket code throughout the gallery, is all that's needed here. Thanks!

[srwiseman]

Ah, understood. You're right, If the demos themselves are not relatively static, then git update-index isn't viable. I'll see if I can come up with a script!

[srwiseman]

I haven't forgotten about this! I'm just very busy with some other projects. I'll do this soon!

[hpinkos]

No worries @srwiseman! No rush here, whenever you have some time to look at it that will be great =)