write the docs!

[jgravois]

patrickarlt [4:15 PM]
if you do want to mess with Typedoc you need TypeStrong/typedoc#549 to make it work.

patrickarlt [4:16 PM]
typedoc --out docs packages/arcgis-core/src --readme none

[4:16]
i dont know how to make typedoc stop treating every file as an external module…

new messages
[4:17]
there supposedly is a --mode modules but it doesn’t do anything.
Dojo has a bunch of custom tooling but their doc ends up looking pretty good https://dojo.io/api/

based on the trouble so far, i'll probably take a stab at running jsdoc on the compiled ES5 source first instead of trying to be a trailblazer.

[tomwayson]

FYI - I've been trying out typedoc for the new lerna monorepo and TS version of cedar and here's my experience.

First, my idea of a minimally viable way to approach this has been to:

• only use typedoc to generate API pages, not complete, integrated pages (including usage, etc) like the new Dojo docs
• to run typedoc once for each package in the monorepo outputting to different folder each time

So the resulting site would have an /api/ section which would link out to /api/cedar, /api/cedar-amcharts/, and /api/cedar-utils, etc. Other sections of the docs /examples, /tutorial, etc would not be generated by typedoc at all. Similar to how we link out to the API section of the angular-esri-map docs pages works. Not ideal, but a simple start that could be improved upon over time.

My first problem was that I was not able to run typedoc from the monorepo root like:

typedoc --out ./site/cedar-utils ./projects/cedar-utils --readme none --theme minimal

When I did it that way I would see a stream of errors for d.ts files under .projects/cedar-utils/node_modules no matter what variation of --exclude, --external etc I used, including:

typedoc --out ./site/cedar-utils --exclude ./packages/cedar-utils/node_modules/ ./packages/cedar-utils/
typedoc --out ./site/cedar-utils --exclude ./packages/cedar-utils/node_modules/**/*.ts ./packages/cedar-utils/
typedoc --out ./site/cedar-utils --externalPattern node_modules/**/*.ts --excludeExternals ./packages/cedar-utils/

I was able to cd into the project folders and successfully run typedoc to output to the root level like:

typedoc --out ../../site/cedar-amcharts . --readme none --theme minimal`

I did have the same problem as @patrickarlt that it treated every file as an external module.

there supposedly is a --mode modules but it doesn’t do anything.

ditto here.

Also, long term, my hope was to create a custom theme, to get the nav/sidebar to match the rest of the non typedoc generated docs, but looking through typedoc issues, it seems like the theming is pretty limited/buggy outside of changing assets and adding custom scripts.

All in all there are a lot of open issues in typedoc, including this interesting one that implies that they are open to a complete shift in architecture, and to me it just feels like it's not ready for prime time.

based on the trouble so far, i'll probably take a stab at running jsdoc on the compiled ES5 source first instead of trying to be a trailblazer.

@patrickarlt so does that mean that we'd lose the auto-documentation of types, etc for function signatures that we get w/ typedoc and have to include all that in comments manually?

[patrickarlt]

@tomwayson I like to approach of a separate section for each package (api/arcgis-reset-js-core) ect. The other alternative would be to do it like Angular does it where all exports are listed on the same page https://angular.io/api. I think either approach is good.

I dug into the Angular approach to TypeScript documentation and it looks like rolled their own called degeni for Angular 1 and for Angular 2 they added TypeScript support. The docs look ok enough that I want to try it.

If that fails then I will look into using the JSON output option on TypeDoc or Dgeni and running it through Acetate to do the templating.

[patrickarlt]

After spending most of yesterday and a few hours this morning on dgeni I finally gave up when it started throwing errors about invalid JSDoc tags when there was nothing invalid about them. dgeni actually suffers from a huge lack of docs and the maintainers push people to really complicated examples like the Angular 1 and Angular 2 docs. it felt like I was rebuilding an entire doc pipeline myself with virtually undocumented tools.

I figured if I was going to have to write my own doc pipeline I might as well use some better/easier tools so I started building a doc pipeline out of Acetate and TypeDoc which I will have a PR for soon.

[patrickarlt]

Doc system is getting started in https://github.com/ArcGIS/arcgis-rest-js/pull/4.