Add versioning to the documentation based on docausaurus

[Meakk]

Context
Currently, the documentation in https://f3d.app is automatically generated when a commit is pushed on master.
Also, the "main" page is based on the readme from github, which is fine but may be a bit disoriented for users not familiat with github.

We need to add a nice looking, web-only welcome page containing:

• A nice image and explanation of what F3D is
• A download button for the last release (as in INSTALATION.md)
• A way to simply jump to the doc of a specific version

Suggested solution

• Craft a welcome page using web skills
• On release make a copy of the website somewhere that do not evolve anymore, store in a dedicated folder in gh-pages
• Add a selector logic in the website to switch between version

Skills

• Jekyll
• Web stuff

Selector code

diff --git a/assets/main.js b/assets/main.js
index a1817087..8d190acf 100644
--- a/assets/main.js
+++ b/assets/main.js
@@ -2,6 +2,26 @@ function onload(event) {
   if (window.location.pathname.endsWith("/INSTALLATION.html")) {
     enhance_install_page();
   }
+  add_version_selector();
+}
+
+const VERSIONS = ["master", "2.4.0", "2.3.0"];
+
+function add_version_selector() {
+  const select = document.createElement("select");
+  for (const version of VERSIONS) {
+    const option = document.createElement("option");
+    option.innerText = version;
+    select.appendChild(option);
+  }
+  select.addEventListener("change", (event) => {
+    window.location.href = event.target.value;
+  });
+
+  select.style.display = "block"; //TODO move to css
+
+  const footer = document.querySelector("footer");
+  footer.insertBefore(select, footer.firstChild);
 }
 
 function enhance_install_page() 

[mwestphal]

just-the-docs has an issue for this but it seems inactive: just-the-docs/just-the-docs#728

[mwestphal]

github-pages-deploy-action seems to be able to deploy to a specific folder. We could deploy master on a dedicated master folder and add a step to the release to generate for release as well.

Then some javascript magic from @snoyer could make the combobox appears ? :)

[mwestphal]

After some investigation by @snoyer and myself, it looks like have an "out of version" welcome page with a javascript based selector should be the way to go, I will edit the issue accordingly

[Ni-g-3l]

Hello,

I have a question ? Using Jekyll is mandatory ? Do you think we can remove Jekyll from doc building system and use only sphinx ?

I made some tests with this theme, and I think we could reproduce the current documentation but with the same 'version selector' system of Blender API (Methods describe here)

Moreover by using sphinx building tool we can directly embed libf3d API doc inside the website and make it more visible than this link.

I found a lot of extensions to prevent convert of current md files to rst so we will just have to update the building tool note documentation

What do you think about that ? I can make some tests if you want I will have some spare time tomorrow

[mwestphal]

Actually this is being discussed on discord and we are thinking to go with docausaurus, please join the discussion there https://discord.f3d.app

[Ni-g-3l]

Sorry, I'm not so active on discord ! I will read the fead asap ! Thanks a lot !

[Ni-g-3l]

Sorry, I'm not so active on discord ! I will read the fead asap ! Thanks a lot !

[mwestphal]

No worries! Let me know if you want a TLDR of the discussion.

[mwestphal]

@chirag-droid has created a prototype of this which is visible here:

#1338

[mwestphal]

More and more people are being impacted by this as we break everything for 3.0, lets display a warning until this is fixed.