Improving API Browsing

[Phuein]

I'm new to BJS, so I'm using the docs to learn. I've noticed some typos, so I forked the docs github and pushed fixes. Nice and simple.

However, when using the API to find more info about classes or methods, it's a pain to scroll through and seek the right one. Even with a page-search (ctrl+f) there's multiple partial results.

So, I wondered if I could add Alphabet linking to Classes, Properties, and Methods - the big lists. So, the top of each list has A, B, C... Z. You click H, and you see all that start with H. Each letter group has a minimalist separation from the others. I searched the github for where to edit and how, but got lost.

Is this possible with the currently used typedocs? Any tips on how to do it? I've read from the typedocs website already, and searched about the docs github, to no avail.

[V!nc3r]

Nice idea, +1 ?

[Guest]

I'm not an expert of TypeDoc but this seems unlikely to me

[Phuein]

On 8/6/2018 at 11:42 AM, Deltakosh said:

I'm not an expert of TypeDoc but this seems unlikely to me

Tsk. Would the person who setup the TypeDoc for BJS know anything about this? Can you tag them? This seems doable but non-trivial.

[Guest]

I did it  I'm the one who setup the TypeDoc

 

[Phuein]

Oh lol. Oh well.

[Sebavan]

Yup it would not be as easy to customize unfortunately.

[V!nc3r]

Because we talking about API doc improvement, is there a way to download a local version of the API  (without having to build or compile or whatever not easy for a non-dev) ? In the same way of Blender Python API for example:

This allow very fast access & searches ('cause sometimes I have to wait the loading/reloading and that's frustrating when you just want to check a little thing).

[Sebavan]

Not yet but it is a good idea, not sure how easy it would be to do so would you mind creating an issue on github ?

 

[V!nc3r]

done

[brianzinn]

1 hour ago, V!nc3r said:

without having to build or compile

I apologize if this is too far off topic, but I wanted to share an option for API offline viewing that does not require build/compile - at least it may help people in the meantime.

I didn't see a way in TypeDoc to generate a full ZIP.  Obviously this is a more involved answer and possibly not for non-devs, but I just want to add that really the best documentation is the source that TypeDoc uses to generate the API docs.  In 2 steps:
1. https://github.com/BabylonJS/Babylon.js/ click download ZIP (or use git -  more difficult to setup, but makes it easy to update your local copy)
2. in VS Code open folder where you unzipped source from #1.

If you don't know where a class is hit "ctrl-t" and type the name.  ie: "environ" will show:

Enable the "outline" (option enabled by right-click on top Explorer bar) - can also use ctrl-shift-o. When you open ie: /src/babylon.scene.ts or Ctrl-T "scene" - you can see the full API (and hidden/private stuff as well that are NOT part of API) in the Outline.  Click the function (ie: createPickingRay) and it brings you right to the source code and API doc in the description.  You can click on methods in the source to navigate, find usages, etc..  It's a bit more work, but very fast and portable. With a couple of hotkeys it's the API + Internals. If you need some offline viewer in the meantime while there is no .ZIP download for docs maybe it will work for you! 

[V!nc3r]

Interesting, I will test that.

However, it's still less convenient that only html static pages (cloning a github repo' can be easy to do thanks to Github Desktop - but needs a github account, and Visual Studio isn't opening as fast as an already opened browser) ; but it looks like allowing quick searches when all is set up

[edit] erf, my note about github account needed is wrong, 'cause as you say we can dl the zip directly

[Phuein]

After figuring out another issue with the docs (adding "Defined in" to API), I felt emboldened to try to figure this feature request once more.

So I spent a few hours. TypeScript... TypeDoc... Grunt... Handlebars....... Okay. So, between the code being in TS (which I don't use) and abstracted even further with Handlebars, I can't even perform basic JS operations on the site. Not without creating a further step that adds my JS into the compiled docs pages, which seems like terribly bad practice.

<rants> What an abstraction nightmare. Taking something simple like JS and turning it into a whole bunch of new API's. ><"

Any idea how I could add a Handlebars Helper function to, and I'm broadly assuming, /typedoc/babylon.d.ts? With that I'd be able to add JS controls to the template file /typedoc/default/partials/index.hbs, which would let me add the nifty index by letter.

[brianzinn]

@Phuein This topic is not super old and maybe is abandoned, but I have actually been working a bunch lately on using the TypeScript compiler to do static analysis on the BabylonJS codebase.  You might end up having some luck writing your own stuff straight-up with the compiler (from typings .d.ts or source).  It is definitely fun to be generating with a compiler!!  I am dynamically generating code from the BabylonJS source for another project.  I think it would be not much more work to generate HTML instead of TypeScript (I am generating TypeScript).  I am able to get all the JSDoc/parameters/classes/methods/etc.  The only snag I hit so far was an interface extending a class in https://github.com/BabylonJS/Babylon.js/blob/master/src/Lights/babylon.shadowLight.ts.  Huuh - wuut???  That is not possible in the languages I am more familiar with like C#/java, but 100% allowed in TypeScript.  I have a PR that is accepted  (https://github.com/dsherret/ts-simple-ast/pull/483) for the compiler API wrapper I'm using.  If you want all the code I am using to parse BabylonJS hit me up (it's ~500 lines).  Be prepared for some pain on the way and rejoicing in the end.  Cheers.  Maybe write your own TypeDoc that is extendable

[Phuein]

I gave up on this idea for the time, yes. Nobody responded with a solution for adding Handlebars Helper functions, which is where I draw my line of bothering with this broken system. (Not being able to add simple JS to a webpage after hours of work means it's broken.)

I'm not following you. How is anything you're saying solving this issue? Why do I need to parse BJS for this? Can you provide code that helps with the actual issue? I definitely don't want to write my own TypeDoc, that would be a waste of my time. I was looking to add a very small and simple letter-index to the existing docs, only.

[brianzinn]

8 hours ago, Phuein said:

How is anything you're saying solving this issue?

If the end result is API docs with letter groups then there are may possible solutions.  One is to generate the HTML from the source and it's not difficult.  I am going to be generating markdown for my project from BJS source and it will be trivial to add letter groups - like I don't think it would even take an extra hour.   I don't have a solution for TypeDoc - I haven't used handlebars for over 6 years.

[Phuein]

I won't redo the entire docs for BJS. Only wanting to add a feature. I'll let the veteran developers decide if they want to redo it. I do agree with you that it should be done.