API Documentation

[ry]

There's nothing yet. Ideally auto-generated from our d.ts files.

Maybe use this https://github.com/tensorflow/tfjs-website/tree/master/build-scripts/doc-gen
Or maybe https://github.com/propelml/propel/blob/master/tools/gendoc.ts

[NewLunarFire]

Why not TypeDoc in this case? I understand you don't like the amount of dependencies it pulls on, but I think it would work fine in our case.

[ry]

@NewLunarFire Last time I looked into it, it wasn't able to generate docs based on the exported symbols of a single declaration file.

[NewLunarFire]

What is the output of the documentation we want? Markdown files for the Github? A proper Documentation website like other Go/Python/Rust have?

Also, once we have the documentation process in place, it will be easier to fill in the gaps where docs are missing and review PRs.

[ry]

@NewLunarFire Some sort of intermediate JSON format would be ideal - we can then generate HTML from that. Here's the JSON format we used in gendoc: https://github.com/propelml/gendoc/blob/master/types.ts#L14-L28

[kitsonk]

Previous experience with TypeDoc is that it will lead to more frustration than solution. In my @dojo days, we spent a lot of time not being happy with TypeDoc. It is a complicated static site generator that is overly opinionated and not designed to be flexible. We tried to use the intermediate JSON format that it does too, but even then, it has a lot of opinions and really wasn't designed to deal with significantly modular TypeScript.

Both the ones you reference look like possibilities. The other thing that I have had good luck with with https://dsherret.github.io/ts-simple-ast/ which gives a good accessible API to deal with a TypeScript AST. It should be fairly straightforward to walk the AST of appropriate modules, either the .d.ts or source .ts.

[NewLunarFire]

gendoc looks good already, and is written by ry and bert. I'm currently looking into it. But if you want to try something with ts-simple-ast it would be interesting to compare both.

[ry]

@NewLunarFire Please also evaluate TFJS's doc-gen. I think it may be more robust and fleshed out. We wrote gendoc before that existed. I'd rather not have to maintain it.

[paldepind]

For what it's worth I've been working on a library that may be suitable. It generates JSON and, optionally, HTML documentation. I made it primarily for the library List after I found TypeDoc to be insufficient for my needs. In case you're curious, the documentation that it generates for List can be seen here.

[NewLunarFire]

@paldepind I'll look into it. Thanks!

[jimmont]

a basic primer/howto wiki page for debugging would be immensely helpful, something along the lines of what the nodejs debugging guide accomplishes but probably much simpler (or whatever is realistic) https://nodejs.org/en/docs/guides/debugging-getting-started/

[ry]

I think we should start with something simpler than API docs. We need a way to get the full typescript declarations of what Deno provides. I propose adding a command line flag:

$ deno --types
declare global {
    interface Window {
        console: Console;
        define: Readonly<unknown>;
    }
    const clearTimeout: typeof timers.clearTimer;
    const clearInterval: typeof timers.clearTimer;
[...]

This should output, to stdout, the complete type declarations of all globals and all built-in modules inside Deno, including JS doc comments.

See #632

[NewLunarFire]

As we keep adding bindings, this is going to become increasingly important. I managed to get this working using tfjs's make-api scripts. What I did

1. Cloned tfjs besides deno
2. cd tfjs-website
3. npm install
4. cd build-scripts/doc-gen/
5. run ../../node_modules/.bin/ts-node make-api.ts --in ../../../deno/js/main.ts --package ../../../deno/package.json --src ../../../deno/js/ --github https://github.com/denoland/deno --repo ../../../deno --out out.json

This generated the intermediary JSON data used by tfjs with the proper JSDoc. The following steps would be to generate a web page using this, with something like a static site generator (Jekyll, Hugo).

The steps to get this working would be:

1. Add the doc-gen folder to third_party, add the required node modules to third_party's package.json
2. Create a docgen.py (or whatever you want to call it) Python script in deno that calls make-api in doc gen with the proper path and arguments.

I would do this but it would take two eternities to merge into Deno, so I would rather someone take the ball on this. After this is done we could look into adding a static site generator or something similar.

[kitsonk]

With the work on #632, I think there is an opportunity to take the output runtime library and generate a JSON structure that could be used to statically generate a website. I am going to take a stab at that.

[bartlomieju]

Autogenerated docs are available at deno.land. For better version lets open new issue.

[ry]

Ya.. we have autogenerated docs.. it's not great and I plan to do something more in this direction.
but let's close this for now.