-
Notifications
You must be signed in to change notification settings - Fork 189
Implement typedoc as replacement for current API builder #713
Comments
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. |
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. |
I'm not used to Gitter but I do like chatting here:) |
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:
|
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. |
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. |
lol |
I think we can use a pug filter to automatically link classes. That way we don't have to pass around paths. |
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? |
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? |
Agree |
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. |
let's discuss it after this one is done ;) |
Should we mark 3.1 class pages as canonical URLs for 3.0 class pages, so that Google will only find the current version? |
This is an excellent idea. |
Obsolete, since we're dropping 3.0 API docs (see comment). Add redirects from We might also want to consider changing |
agree |
Done:) |
Follow-up to #712.
Preparations:
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.Tasks:
Unresolved issues:
_
prefix) are not excluded.The text was updated successfully, but these errors were encountered: