[Feature] Migrate documentation to Vitepress for enhanced DX and UX

[daker]

Motivation

The current vtk.js documentation system lacks modern features and a streamlined development experience, hindering contributions and making it less user-friendly.

Detailed Description

This migration will significantly improve the vtk.js documentation, making it more accessible and maintainable for both developers and users.

[daker]

Some in progress work :

[jourdain]

How do you get nested hierarchy in the menu?

[daker]

@jourdain i am generating the sidebar config using vitepress nested items, here is the code

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const cwd = path.join(__dirname, '..', '..', 'Sources');

function walkSync(dir, filelist = []) {
  fs.readdirSync(dir).forEach((file) => {
    const fullPath = path.join(dir, file);
    if (fs.statSync(fullPath).isDirectory()) {
      walkSync(fullPath, filelist);
    } else if (file === 'api.md') {
      filelist.push(fullPath);
    }
  });
  return filelist;
}

function generateSidebarConfig() {
  const apiFiles = walkSync(cwd);
  const sidebarStructure = {};

  apiFiles.forEach((file) => {
    const relativePath = path.relative(cwd, file);
    const parts = relativePath.split(path.sep);
    let current = sidebarStructure;

    // Create nested structure
    for (let i = 0; i < parts.length - 1; i++) {
      const part = parts[i];
      if (!current[part]) {
        current[part] = {};
      }
      current = current[part];
    }
  });

  // Convert structure to VitePress sidebar format
  function convertToSidebarItems(obj, parentParts = []) {
    return Object.keys(obj).map((key) => {
      const value = obj[key];
      const newParts = [...parentParts, key];
      const children = Object.keys(value);
      if (children.length > 0) {
        return {
          text: key,
          collapsed: true,
          items: convertToSidebarItems(value, newParts),
        };
      }
      // Leaf node: link to url, ex: /api/Rendering_Core_RenderWindow.html
      const linkName = `/api/${newParts.join('_')}.html`;
      return {
        text: key,
        link: linkName,
      };
    });
  }

  const apiSection = {
    text: 'API',
    collapsed: false,
    items: convertToSidebarItems(sidebarStructure),
  };

  const sidebar = {
    '/': [
      {
        text: 'Getting Started',
        collapsed: true,
        items: [
          { text: 'Introduction', link: '/index' },
          { text: 'Tutorial', link: '/tutorial' },
        ],
      },
      // Add other static sections here
      apiSection,
    ],
  };

  // Write the sidebar configuration
  const sidebarConfig = `import { DefaultTheme } from 'vitepress'

export const sidebar: DefaultTheme.Sidebar = ${JSON.stringify(
    sidebar,
    null,
    2
  )}`;

  fs.writeFileSync(
    path.join(__dirname, '..', '.vitepress', 'sidebar.ts'),
    sidebarConfig
  );
  console.log('Sidebar configuration has been generated!');
}

generateSidebarConfig();