Generating docs from DefinitelyTyped type definitions?

[Bartvds]

Have you ever thought about using typedoc to generate documentation from type definitions?

I collaborate on DefinitelyTyped organisation and since we're sitting on this huge wealth of information we have this vague idea to generate documentation from all the type definitions.

I tried it with the typedoc commandline tool but it didn't work out-of-the-box.

If you'd feel like pursuing this we could put the output on http://definitelytyped.org website: we have automated builds and stuff and are looking at some webhooks so it could be very cool.

[sebastian-lenz]

Currently parsing of declaration files is explicitly blocked as in most use cases this will be not desired.

But parsing DefinitelyTyped seems interesting, as it is also a great test for the generated documentation. I've added a switch to turn on parsing of declaration files but I quickly ran into some issues. I'll have a look at those in the next days.

[Bartvds]

Glad to hear you're interested in this. The content in DT is really varied in complexity and code patterns, so it'll be a fun fuzz-test for your system.

And I'm cursed with ideas on how to make this extra useful for this specific case but we'll see about those if it the basics work out.

[JeroMiya]

We absolutely need an option to generate documentation for declaration files. In our case, we have some code still in JavaScript but we provide TypeScript declaration files for them, so we still need documentation for these declaration files.

The other issue is that, without generating documentation for the declaration files, users can't click through to third party library types like ng.IScope when they are referenced from our documentation. This suggests that, we need to still generate documentation for the third party libraries. However, you would display them in a separate "third party libraries" section of the documentation that, while still linkable from our part of the app, is still segregated from "our code" so that our namespace list isn't spammy.

[Edit: Actually, since there is already a set of 'filter-like' flags in the title bar, I would just add a new 'third party libraries' flag there]

[Bartvds]

Hah! :sparkles::rocket::sparkles:

Quick-n-dirty first total build (why start slow? :wink:

http://definitelytyped.org/docs/ (not linked, just for fun & testing)

It took Travis 13 minutes on 24 cores/threads to bake 531 pages, nicely inefficient with duplicate assets and everything.

https://github.com/DefinitelyTyped/docs/tree/gh-pages

No idea what that means, but the basic system works so that's cool. :ice_cream:

[sebastian-lenz]

That is really awesome! This is the first time I actually would like to have a twitter account ;)

Had it running several times on my machine and noted the long runtime. TypeDoc writes nearly 30000 files and over 1.5GB must be saved to disk on the other hand.

The generator runs the compiler for each of the nearly 500 projects and I guess half of time it has to parse jQuery. We could bundle several projects in one compiler run, but this would need some changes right at the compiler and we must resolve the references manually. The compiler is currently completely invoked, so it actually reaches the state at which the final javascript has been generated. Some cpu cycles could be saved right here, but I was not able to figure out at which earlier point the complete declaration structure exists and could be extracted. As the compiler comes with no documentation some more trial and error is required here. We could also include an option to run the compiler only if any of the source files have changed, for sure the simplest solution but might be sufficient.

The duplicate assets could easily be avoided by using a custom theme.

I'm still checking the output of DefinitelyTyped and try to improve it, the current version on git already contains some of the improvements. Hopefully we reach a state the documentation is of publishable quality.

[Bartvds]

Oh, I never had the full thing locally, it was all an accident (I botched a sanity filter to only run a few folders on Travis, but decided to let it run).

I checked-out gh-pages and indeed it's over 1.6GB...heh... my explorer almost dies but then says 31K files.. compresses really well in Git though.

Total runtime is not a huge problem, at some point the DT repo tester ran for an hour, before we parallelized it and added a change-detector script. File-size is bigger issue. I guess I can compress the html somewhat, and try to share all the CSS and other static assets. If we pursue this a change-detector should be possible here too.

I'm surprised it all works though.. node & git and everything are pretty powerful :smile:

Anyway we'll continue this of course, but I'll have to think about how to handle deployment. Probably time to hustle a sponsored CDN somewhere.

[Evgenus]

It looks like that was a "dry run". No documentation produced http://definitelytyped.org/docs/jquery--jquery/modules/jquery.html for pretty much documented source https://github.com/borisyankov/DefinitelyTyped/blob/master/jquery/jquery.d.ts . Isn't it?

I'm very interesting in this issue as typescript developer and as DT contributor. So +1. Let's do this.

[sebastian-lenz]

Yes, this issue looks a bit abandoned and the test documentation you are referring to is quite empty. But we are working on this issue, definitelytyped.org will be relaunched with a new design and a package listing. The later one is a prerequisite to create pages for deeplinking to a definition which can be used to display the documentation pages. So, we still have a long road before us but we are actively working on this.

The demo is a proof of concept to test the deployment process of the docs. As DT contains really a lot of definitions, we ran into issues to. The process took really a lot of cpu power and the resulting html pages consume a notably amount of disc space. To solve this we are investigating whether we could move the deployment to an own host and introduce some real hosting.

The demo you see was created with an old version of TypeDoc, the new version produces a documentation for jQuery containing all the comments in the definitions. So if you are working on definition files, don't be afraid of that one and include some doc comments, once the docs will become real, the comments will be reflected.

[Bartvds]

It definitely was just an experiment to see if it could be done and how it would behave. It is very much non optimised so it's just 500+ individual documentations (with all the duplicate stylesheets etc).

I think if we'd optimised the template and generation so that we don't generate so many duplicate stuff and then run it though a html minifier we can totally make it work.

@sebastian-lenz I think you should have push access to the repo too, so if you feel a need to mess with this then go ahead.

[jvilk]

@Bartvds nice! Looks like my effort in completely documenting Microsoft-Live-Connect resulted in some nice documentation (although a lot of the sidebar stuff is from pulled-in dependencies):

http://definitelytyped.org/docs/microsoft-live-connect--microsoft-live-connect/interfaces/microsoft.live.api.html