Versioned Documentation

Hi :wave:

Since this is my very first post here … hello, I guess :blush:
And thank you all so much for babylon.js!

My question / feature request:
Are there any plans to add versioning to the documentation? I see this frequently in code docs, where you would have the version you’re currently viewing somewhere on top.
Material UI and Laravel (sorry, can only put 2 links …) come to my head first as examples, but there are plenty.

Right now, as far as I can tell, the BJS docs are for the v5 alpha – which is pretty unexpected. Doing an innocent npm i @babylonjs/core would give me v4, and I’m instantly at odds with the docs.

@RaananW @PirateJC I saw there are plans to upgrade the docs – will this feature be included?

Although this didn’t get a lot of attention, seems like I’m not the only one who’d find this useful.

3 Likes

Welcome to the community !!!

You already pinged to right persons for the doc, so I am only stopping by to say Hi :wink:

1 Like

Hi guys!
I’d like to add my two cents. Many times I see small issues with the documentation, typos or incorrect example code. These are mainly problems that many developers can figure out without help. The beginners may struggle however. It would be cool to have a “Suggest edit” on each page, so contributing small changes wouldn’t require all the hassle creating a PR.

Regarding the versioning I was surprised too that the docs are for the latest alpha but it actually didn’t bother me anymore because I’ve switched from 4.2 to 5 alpha in our project long ago. The guys at BabylonJS are fixing issues really fast and reliable! I have no fear that I’ll get stuck with the alpha version so for me 5 alpha is already production :slight_smile: I think BJS has only one codebase for the docs, there are a lot of contributions to it (v4 or v5 related) and it is not possible to separate it anymore. Or am I wrong?

Have a nice day!

EDIT: I can prepare a PR for the Suggest Edit functionality if it makes sense for you :vulcan_salute:

6 Likes

IMHO the best way to suggest edits to the docs is in on this forum. All the contributors to the docs come to the forum regularly and mentioned doc errors are corrected quickly. To have to also check for comments on the docs elsewhere could be a bit of a chore.

Provided the typos, incorrect code, etc. are not in the API section of the docs; any forum member who reads about a suggested edit for the docs who has a github account can suggest and edit directly fairly easily using The Easy Way to Edit the Docs. The API section is generated directly from comments in the code base and so a ‘simple’ edit is not possible.

However if you would explain in a little more detail how your “suggest edit” would work in practise others might think differently.

2 Likes

Hi @panepeter and welcome to the community

Please note that the this topic does not so much refer to documentation of older versions of the Babylon.js codebase but to a different structure for the documentation itself. The API section of the older style documentation was still generated by the most current alpha version of the codebase.

1 Like

Hey @panepeter , welcome to the forum :slight_smile:

Wow, that’s a great topic! I’ll start by saying - I totally understand what you mean, and we should honestly address it pretty soon.

Let’s separate the API documentation and the actual doc pages (though i know they are hosted on the same website).
The API/TypeDoc page is generated using the latest nightly. As tsdoc sadly doesn’t support the @since tag for anything other than class, we are still trying to find the best way to be able to show you the version in which a certain function was added. This is on our todo list. We also have different packages, and we need a link to the sourcecode, and more and more. We know it’s not perfect, and are trying to get it to work the best we can :slight_smile:

Now, the website and the docs themselves. Babylon is (and always will be) backwards compatible. Meaning, any code found in the docs should work on every version, unless (and this is where you are totally right!) the feature was added in the current version. We do our best to document in which version a certain feature was added, but sometimes we simply forget.

I like your suggestion to have different doc pages for different versions (taking this outside of the typedoc scope that will be addressed in a month or two). I’d be happy to invest some time to see how we can best support that when I get the chance.

5 Likes

Oh man you are totally right! I forgot about this easy option, shame on me :blush:

Ok, so what could help here is a link to the github page so one can start to create the PR without looking up the right page to edit.

2 Likes

Agree! It could help a lot to spot the right page in a second (until now, I open the repo on Visual Studio Code then do a global search with a piece of text from the page I want to tweak, to find the right markdown file without manually checking all file tree :crazy_face:)
image

4 Likes

Wow, thanks a lot for all the quick responses! I guess “a great forum and a tremendous community” was not an exaggeration :wink:

The quick way for editing doc pages definitely is a goodie, bookmarked that one!

Thanks also for pointing out the distinction between the written doc pages and the generated API docs. Since this is a TS project (thanks so much for that), I usually don’t bother much with the latter.
Still - the fact that it’s fully generated should (in my very naive, outside-look mindset) make it easier to publish it for different versions.

Doing the same for the written pages is a whole different story, I came to realise that.

Anyways, I’m glad there is general agreement and awareness that this feature would be desirable. Of course, I totally understand this is not #1 on the list of priorities.

I’ve created a PR for giving this more visibility in the docs. Please proceed with it as you see fit.

I certainly cannot promise anything (who can …), but I hope to get more involved here over time. But, as you can see, I’m still at the basics :grimacing:

4 Likes

Hi @RaananW! Hello everyone!

I’ve created an Edit on GitHub button which is displayed on every page just above the scroll to top button. It just opens a new tab with the current page on GitHub.

Good enough for a PR?

Thank you!
R.

Without the tooltip displayed:

4 Likes

Looks pretty good to me :slight_smile:

1 Like

That looks great! Please submit the PR :slight_smile:

I would put it at the bottom of every page (and not sticky to the scroll-to-top), as it is not a functionality that everyone will use constantly.

3 Likes