Create page for deeplinking to a definition

[Bartvds]

Create an info page to show info and instructions for a specific definition.

1. Needs a permanent URL
2. Can be client side with some JavaScript
3. Future ready for when we add a browsable content list

[sebastian-lenz]

We somehow forgot this issue while discussing #14. With an index on the homepage we won't get no deeplinks. However there are still the docs floating around. Also on the demo the dependencies of each module are listed but not clickable - mainly cause it's difficult to link to another tab within the list.

My first tryout with the DocPad plugin produced individual pages for each module but was dismissed due to the update problem. Same goes for the documentation update process, see DefinitelyTyped/docs#2.

We could remove the readme page of the documentation and replace it with something like we have in the packe list accordion so we would have both a deeplink for each project and the documentation. But we still have a problem with updating everything. Maybe we should "Find some real hosting" for definitelytyped.github.io?

[Bartvds]

Ok, long one because it is complicated (as always :)

For the deeplinking we could consider using a hash, like http://definitelytyped.org/#!/foo/bar.d.ts. Maybe do some trickery with pushState API to have it on a dedicated page? (using an index.html in a subfolder).

Main thing is they should be permanent so we don't break inbound links easily.

For hosting we got a new option: I use free hosting on OpenShift for some experiments, it is slowish for serving sites, but it could probably handle a periodic docpad build+publish if we need it; we'd use a webhook on both the main def repo and the site content itself. Then we could still use the github.io hosting for the free & fast bandwidth.

That'd mean we could actually use real pages instead of a #hash. I'll see if I can do a test run for docpad on OpenShift, just to see how long it takes the crummy free gear (unlike Travis it is persistent so saves a lot on reinstalling docpad/grunt from npm each time).

But a problem with the /docs is it takes quite a lot of raw power to generate them, even at 24 cores on Travis it takes many minutes and a shitload of disk space (I think we can cut down a lot by using shared assets and some compression, but still it'll be a far chunk of html). I think the OpenShift hosting will melt-down.

It has been mentioned on an earlier email that we should just get some company to sponsor us. I think we have a good chance a platform like Azure could be hustled for one or two node hosts (small one for a simple express-like webserver, and maybe a fat one for heavy data rebuilds). We sort of left that open while we were looking for candidates to beg stuff from.

[sebastian-lenz]

The pushState API would require some server setup (mod_rewrite or similar) we cannot access on GitHub pages I guess, so only the hash/query string option remains. For permanent links real urls seem preferable somehow.

Also delivering the pages through some javascript application will turn the pages invisible for search engines. If I get your idea right for http://definitelytyped.org/#!/foo/bar.d.ts to be indexed we must supply a page http://definitelytyped.org/?_escaped_fragment_=/foo/bar.d.ts (according to this) which would also require server side logic or a page to be rendered beforehand.

The performance required to generate docs could be greatly lowered if we only rebuild the docs that have actually changed. Most of the time we properly won't need to recompile and rebuild every package. Also I've changed TypeDoc to consume less disc space and less CPU cycles. I would like to build a theme that matches the new design of definitelytyped.org, that shares the assets of the website and that renders the package info to the index page.

Azure seems to suggests itself 😉 But you seem to be very talented in using services like Travis and OpenShift for your own purpose, so as long as we can squeeze the pages onto the GitHub server and add some optimizations to the generator we maybe can go with those too.