Since this is my very first post here … hello, I guess
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.
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 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
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.
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.
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
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.
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 )
Wow, thanks a lot for all the quick responses! I guess “a great forum and a tremendous community” was not an exaggeration
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
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.
I know I’m bringing up an old thread, but it seems like a relevant place to continue this discussion. As far as I know this is still a problem and hurts the developer experience at times.
For example, I just spent a good deal of time searching for an alternate solution to a problem in our application. After reading through a bunch of API documentation, I had finally pieced together a solid solution to the problem. I was stoked until I began implementing it and realized the features aren’t available in the version of Babylon this project uses.
We are using 5.57.1 and aren’t in a place to upgrade major versions. So now instead of relying on the documentation to understand the API, which is the purpose of the documentation, I’m stuck having to read through the source code.
If we wanted to suggest the team upgrades the BabylonJS version to gain certain functionality to solve a problem, I first have to search through version specific code until I figure out when the feature was first implemented and find the common denominator. Its just not the ideal developer experience.
Given how well backwards compatibility is maintained in BabylonJS, I don’t think its necessary to keep documentation for all versions, but it would really be nice if some old version documentation was still accessible. Even just the final version of each major release would be sufficient.
I know its been a few years since this was posted, so I’m hoping someone will come along and be able to point me to the legacy documentation I’m missing, but if not please consider how this can be achieved.
I assume this is mainly referring to the API documentation.
Yep, this is something I am planning on doing when moving the docs to the main repository (there is already an open issue on github for that).
The idea is that we will be able to run typedoc directly from the source, per version, and serve typedoc based on the version you need.
For Babylon developers and the team in general - the best way to tackle this until then is to add @since to the code doc of a newly added function. This will be populated on the next release and will be a good indicator from which version of the engine you can use a specific function. If you want to force a specific version, just add the version. i.e. - @since 7.1.0
I appreciate all of your quick responses! @RaananW Yes, I was mostly referring to the API documentation.
I’d consider building the documentation repo locally and serving it to my team, but I’m not sure how to know the right commit to check out for a given version.
For now its easier to check with the Web Archive. Based on NPM, it looks like version 5.57.1 was released on March 24th, 2023, but version 6.0.0 appears to have been released on March 14th, 2023.
I used the web archive to check the docs for a few around that time. The What’s New page doesn’t show version 6.0.0 until April 26th, 2023. The next previous date archived is April 4, 2023.
Is is safe to assume that if the docs don’t include 6.0.0 in the What’s New page that the API documentation definitely won’t include anything newer than 5.57.1? If not, is there a definitive way to know that the documentation doesn’t include anything newer than 5.57.1?
Oh, good question! 6.0.0 was released officially on april 20th 2023. 5.57.1 on the 19th of April. So anything before 20th of april 23 is 100% in 5.57.1
What is more than viable in your case is to generate typedoc directly from source based on the version tag. Best practice here would be to checkout the tag, build the es6 package(s) (npm run build:es6) and then generate typedoc from the public package’s directory. This will guaranty that you have the right version and the right API references.
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?
)
