Implement typedoc as replacement for current API builder

[mootari]

Follow-up to #712.

Preparations:

• The file data/classes-tags.json that gets generated during the build (from markdown metadata in the class files) will have to be added to the repo.
• Remove obsolete importer code #714

Tasks:

• Setup a script to generate API pages for https://github.com/BabylonJS/Babylon.js/tree/master/src using http://typedoc.org/
• Create a configuration and custom theme to match the current final html output.
  • Limit output to index and class files.
  • Make file names match current structure.
  • Make links match current paths.
  • Make handlebar layouts to match current class output (minus sidebar index).
  • Include sidebar index (without tags).
  • Add tag groups to sidebar index.
  • Add tag groups to index.
  • Header, banner, footer includes: Either include rendered pug includes or port includes to handlebars.
  • Pass through custom options (instead of hardcoding values).
• Remove markdown class files.
• Perform a final review
• Publish

Unresolved issues:

• entryPoint cannot be set. Resolved via --entryPoint is broken for .d.ts files TypeStrong/typedoc#511 (comment).
• When a series of docblocks is used (e.g. getter/setter in ColorCurves) only the first block gets rendered.
• Implicitely private members (_ prefix) are not excluded.
• Line breaks in docblocks are lost.

[mootari]

TypeDoc looks promising, but has issues of its own. We'll definitely need a custom theme, and rendering markdown files doesn't seem to be supported easily/natively (TypeStrong/typedoc#174 and related issues).

Another problem is that the API docs need to be integrated into the existing site structure. I didn't dive in too deep in the current building process, but I expect that this will be too involved for the moment.

[mootari]

Any chance we could create a gitter for this repo and get the team to join there? Would be great if I could just throw in some question now and then about the current structure without having to abuse the issues as a Poor Man's Chat.

[deltakosh]

I'm not used to Gitter but I do like chatting here:)

[mootari]

Well, this is fun. The gist of the classes markup is created in the various writers as markdown, then later on rendered. These parts need to be moved to pug mixins. Strategies:

1. Extract from builder and compiler script.
   • Pros: Easier to spot individual components.
   • Cons: Working in multiple files, lots of interdependencies. Also, maek brain hurrt.
2. Reverse engineer from compiled html files.
   • Pros: Porting is fairly straight forward.
   • Cons: Tag soup, might miss certain cases.

[mootari]

Might be a good idea to get rid of any markup in the scripts and instead pass everything through pug templates. That would include any customizations to the markdown renderer output.

[deltakosh]

As long as we can keep the content into md I'm fine with all required changes

[mootari]

As long as we can keep the content into md I'm fine with all required changes

Yeah, I'm definitely not touching those. On the contrary, I think we can move some metadata from statics.json into the md files. But that's a project for another day.

[deltakosh]

lol

[mootari]

I think we can use a pug filter to automatically link classes. That way we don't have to pass around paths.

[mootari]

Enums in current docs are slightly broken: https://doc.babylonjs.com/classes/3.1/orientation

What should this look like? Skip the second heading and simply print "enumeration" inside a paragraph?

[mootari]

Constructors: https://doc.babylonjs.com/classes/3.1/action

Is the whole constructor signature really supposed to be wrapped in h2? Looks like an oversight / error to me?

[deltakosh]

Agree

[mootari]

Btw, I was wondering (again, project for another day): Perhaps we should handle all redirects through express (we could still keep them in a json)? That would allow us to keep tabs on the ones that are actually needed (and purge obsolete ones after a while). Additionally we could implement some fuzzy logic in case of 404's or display a page with search results (while still issuing a 404, of course). This also lessens the dependency on Netlify's redirect feature.

[deltakosh]

let's discuss it after this one is done ;)

[mootari]

Should we mark 3.1 class pages as canonical URLs for 3.0 class pages, so that Google will only find the current version?

[deltakosh]

This is an excellent idea.

[mootari]

Should we mark 3.1 class pages as canonical URLs for 3.0 class pages, so that Google will only find the current version?

Obsolete, since we're dropping 3.0 API docs (see comment). Add redirects from /classes/3.0/* and /classes/3.1/* paths to /classes/stable/* instead, with a final catchall to the /classes/stable index page.

We might also want to consider changing /classes to /api.

[deltakosh]

agree

[deltakosh]

Done:)