New docs site (#318)

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+# Reference: https://vitepress.dev/guide/deploy#github-pages
+
+name: Deploy VitePress site to Pages
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+defaults:
+  run:
+    # All jobs in this workflow run from the docs directory
+    working-directory: docs
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install npm packages
+        run: npm ci
+      - name: Build JS API docs
+        run: npm run build-js
+      - name: Build .NET API docs
+        run: npm run build-dotnet
+      - name: Render docs with VitePress
+        run: npm run build
+      - name: Copy images
+        run: cp -r images .vitepress/dist/images
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -15,3 +15,6 @@ examples/**/package-lock.json
 
 *.log
 *.binlog
+
+cache/
+dist/

Directory.Build.props

@@ -61,10 +61,12 @@
 
   <PropertyGroup Condition=" !$(NetFramework) AND !$(NetStandard) ">
     <!-- A few runtime features are unavailable in .NET Framework and require conditional compilation. -->
-    <DefineConstants>$(DefineConstants);UNMANAGED_DELEGATES</DefineConstants>
     <DefineConstants>$(DefineConstants);STRING_AS_SPAN</DefineConstants>
     <DefineConstants>$(DefineConstants);STREAM_MEMORY</DefineConstants>
     <DefineConstants>$(DefineConstants);READONLY_SET</DefineConstants>
+
+    <!-- The xmldoc markdown tool doesn't support unmanaged delegates. -->
+    <DefineConstants Condition=" '$(GenerateDocumentationFile)' != 'true' ">$(DefineConstants);UNMANAGED_DELEGATES</DefineConstants>
   </PropertyGroup>
 
   <Import Project="./rid.props" />

Directory.Packages.props

@@ -16,5 +16,6 @@
     <PackageVersion Include="xunit" Version="2.4.2" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.4.5" />
     <PackageVersion Include="Xunit.SkippableFact" Version="1.4.13" />
+    <PackageVersion Include="XmlDocMarkdown.Core" Version="2.9.0" />
   </ItemGroup>
 </Project>

README.md

@@ -110,7 +110,7 @@ dotnet.ExampleNamespace.ExampleClass.ExampleMethod(...args); // This call is typ
 
 (CommonJS modules must use `require()` instead of `import`.)
 
-For reference, there is a [list of C# type projections to TypeScript](/Docs/typescript.md).
+For reference, there is a [list of C# type projections to TypeScript](/docs/typescript.md).
 
 ### Full async support
 JavaScript code can `await` a call to a .NET method that returns a `Task`. The marshaller
@@ -282,12 +282,12 @@ For details, see [Using .NET Generics in JavaScript](./docs/generics.md).
 
 #### Instructions
 For calling .NET from JS, choose between one of the following scenarios:
- - [Dynamically invoke .NET APIs from JavaScript](./Docs/dynamic-invoke.md)<br/>
+ - [Dynamically invoke .NET APIs from JavaScript](./docs/dynamic-invoke.md)<br/>
    Dynamic invocation is simpler to set up: all you need is the `node-api-dotnet` npm package and
    the path to a .NET assembly you want to call. But it has some limitations (not all kinds of APIs
    are supported), and is not quite as fast as a C# module, because marshalling code must be
    generated at runtime.
- - [Develop a Node module in C#](./Docs/node-module.md)<br/>
+ - [Develop a Node module in C#](./docs/node-module.md)<br/>
    A C# Node module is appropriate for an application that has more advanced interop needs. It can
    be faster because marshalling code can be generated at compile time, and the shape of the APIs
    exposed to JavaScript can be adapted with JS interop in mind.
@@ -330,4 +330,4 @@ third-party's policies.
 <br/>
 <br/>
 
-![.NET + JS scene](./Docs/images/dotnet-bot_scene_coffee-shop.png)
+![.NET + JS scene](./docs/images/dotnet-bot_scene_coffee-shop.png)

docs/.gitignore

@@ -0,0 +1,6 @@
+# API doc files are generated by the XmlDocMarkdown tool.
+/reference/dotnet
+/reference/js
+
+# Temporary files generated by vitepress
+/.vitepress/.temp

docs/.vitepress/config.mts

@@ -0,0 +1,122 @@
+import { defineConfig } from 'vitepress'
+import dotnetApiNavTree from '../reference/dotnet/nav.mjs'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Node API for .NET",
+  description: "Advanced interoperability between .NET and JavaScript in the same process",
+  lang: 'en-US',
+  base: '/node-api-dotnet/',
+
+  metaChunk: true,
+
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+
+    logo: '/images/node-api-dotnet-logo.svg',
+
+    sidebar: [
+      { text: 'Overview', link: '/overview' },
+      {
+        text: 'Get Started',
+        items: [
+          {
+            text: 'JS / .NET interop scenarios',
+            link: '/scenarios/index',
+            collapsed: false,
+            items: [
+              { text: 'Dynamic .NET from JS', link: '/scenarios/js-dotnet-dynamic' },
+              { text: '.NET module for Node.js', link: '/scenarios/js-dotnet-module' },
+              { text: '.NET Native AOT for Node.js', link: '/scenarios/js-aot-module' },
+              { text: 'Embedding JS in .NET', link: '/scenarios/dotnet-js' },
+            ],
+          },
+          { 'text': 'Requirements', link: '/requirements' },
+          { 'text': 'Example projects', link: '/examples' },
+        ]
+      },
+      {
+        text: 'Features',
+        items: [
+          { text: 'Type definitions', link: '/features/type-definitions' },
+          { text: 'JS / .NET Marshalling', link: '/features/js-dotnet-marshalling' },
+          { text: 'JS types in .NET', link: '/features/js-types-in-dotnet' },
+          { text: 'JS value scopes', link: '/features/js-value-scopes' },
+          { text: 'JS threading & async', link: '/features/js-threading-async' },
+          { text: 'JS references', link: '/features/js-references' },
+          { text: '.NET Native AOT', link: '/features/dotnet-native-aot' },
+          { text: 'Performance', link: '/features/performance' },
+        ]
+      },
+      {
+        text: 'Reference',
+        items: [
+          {
+            text: 'JS / .NET type mappings',
+            link: '/reference/js-dotnet-types',
+            collapsed: true,
+            items: [
+              { text: 'Basic types', link: '/reference/basic-types' },
+              { text: 'Null & undefined', link: '/reference/null-undefined' },
+              { text: 'Classes & interfaces', link: '/reference/classes-interfaces' },
+              { text: 'Structs & tuples', link: '/reference/structs-tuples' },
+              { text: 'Enums', link: '/reference/enums' },
+              { text: 'Arrays & collections', link: '/reference/arrays-collections' },
+              { text: 'Delegates', link: '/reference/delegates' },
+              { text: 'Streams', link: '/reference/streams' },
+              { text: 'Dates & times', link: '/reference/dates' },
+              { text: 'Other special types', link: '/reference/other-types' },
+              { text: 'Async & promises', link: '/reference/async-promises' },
+              { text: 'Ref & out parameters', link: '/reference/ref-out-params' },
+              { text: 'Generics', link: '/reference/generics' },
+              { text: 'Extension methods', link: '/reference/extension-methods' },
+              { text: 'Overloaded methods', link: '/reference/overloaded-methods' },
+              { text: 'Events', link: '/reference/events' },
+              { text: 'Exceptions', link: '/reference/exceptions' },
+              { text: 'Namespaces', link: '/reference/namespaces' },
+            ],
+          },
+          { text: 'MSBuild properties', link: '/reference/msbuild-props' },
+          { text: 'Packages & releases', link: '/reference/packages-releases' },
+        ]
+      },
+
+      // API docs might belong under "Reference", but the vitepress sidebar has a max depth of 6,
+      // which .NET API docs would exceed if they were one level deeper.
+      {
+        text: 'JavaScript APIs',
+        items: [
+          {
+            text: 'node-api-dotnet',
+            link: '/reference/js/',
+          }
+        ]
+      },
+      {
+        text: '.NET APIs',
+        link: '/reference/dotnet/',
+        items: dotnetApiNavTree,
+      },
+
+      { text: 'Support', link: '/support' },
+      { text: 'Contributing', link: '/contributing' },
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/microsoft/node-api-dotnet' },
+    ],
+
+    search: {
+      provider: 'local',
+    },
+
+    editLink: {
+        pattern: 'https://github.com/microsoft/node-api-dotnet/docs/:path',
+    },
+
+    footer: {
+      message: 'Released under the MIT license',
+      copyright: 'Copyright © 2023-present Microsoft',
+    }
+  }
+})

docs/.vitepress/theme/custom.css

@@ -0,0 +1,10 @@
+/*
+ * This file has customizations for the VitePress default theme. For a list of
+ * variable defaults that can be overridden, see
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+:root {
+  /* The default sidebar width is 272px. We need extra width for a deep API doc tree. */
+  --vp-sidebar-width: 400px;
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme

docs/contributing.md

@@ -0,0 +1,9 @@
+---
+prev: false
+next: false
+---
+
+# Contributing
+
+https://github.com/microsoft/node-api-dotnet?tab=readme-ov-file#contributing
+https://github.com/microsoft/node-api-dotnet/blob/main/README-DEV.md

Docs/dynamic-invoke.md → docs/dynamic-invoke.md

@@ -1,8 +1,9 @@
 ## Dynamically invoke .NET APIs from JavaScript
 
-For examples of this scenario, see
-[../examples/dynamic-invoke/](../examples/dynamic-invoke/) or
-[../examples/semantic-kernel/](../examples//semantic-kernel/).
+For examples of this scenario, see the
+[dotnet-dynamic](https://github.com/microsoft/node-api-dotnet/tree/main/examples/dotnet-dynamic) and
+[semantic-kernel/](https://github.com/microsoft/node-api-dotnet/tree/main/examples/semantic-kernel)
+projects.
 
 1. (Optional but recommended) Create a `.csproj` project (without any `.cs` source files) that will
    manage restoring nuget packages for .NET assemblies used by JS:

docs/examples.md

@@ -0,0 +1,4 @@
+# Example Projects
+
+See the [examples](https://github.com/microsoft/node-api-dotnet/tree/main/examples) directory in
+the repo.

docs/features/dotnet-native-aot.md

@@ -0,0 +1,44 @@
+# .NET Native AOT
+
+This project supports loading .NET libraries into a JavaScript application process,
+or loading JavaScript libraries into a .NET application process. In either case the .NET
+code can be
+[ahead-of-time (AOT) compiled](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/),
+which makes it executable _without depending on the .NET Runtime_.
+
+There are advantages and disadvantages to either approach:
+|                     | .NET Runtime | .NET Native AOT |
+|---------------------|--------------|-----------------|
+| API compatibility   | Broad compatibility with .NET APIs | Limited compatibility with APIs designed to support AOT |
+| Ease of deployment  | Requires a matching version of .NET to be installed on the target system | A .NET installation is not required (though some platform libs may be required on Linux)
+| Size of deployment  | Compact - only IL assemblies need to be deployed | Larger due to bundling necessary runtime code - minimum ~3 MB per platform |
+| Performance         | Slightly slower startup (JIT) | Slightly faster startup (no JIT) |
+| Runtime limitations | Full .NET functionality | Some .NET features like reflection and code-generation aren't supported |
+
+To use C# to create a Node.js addon using Native AOT, see
+[.NET Native AOT for Node.js](../scenarios/js-aot-module).
+
+There is no documentation or example code yet specific to hosting JavaScript in a .NET Native AOT
+application, but it is not very different from non-AOT
+[Embedding JS in .NET](../scenarios/dotnet-js).
+
+## AOT limitations
+
+Some features in this project are not available in a Native AOT environment because they depend
+on runtime reflection or code-generation:
+ - [Dynamically loading and invoking .NET APIs](../scenarios/js-dotnet-dynamic) - Only APIs tagged
+   with `[JSExport]` and
+   [compiled with the source-generator](./js-dotnet-marshalling#compile-time-code-generation) can
+   be called in an AOT module.
+ - [.NET namespaces](../reference/namespaces) - Namespaces are used only with dynamic invocation.
+   APIs exported by an AOT module do not use JS namespaces.
+ - [Constructing generic classes or invoking generic methods](../reference/generics) - AOT modules
+   can only export non-generic types and methods.
+   ([Generic collections](../reference/arrays-collections) are supported though.)
+ - [Calling .NET extension methods using extension syntax](../reference/extension-methods).
+   Extension methods can still be called using static-method syntax, but AOT modules should design
+   exported APIs to not require extension methods.
+ - Implementing a .NET interface with a JavaScript class - this requires code-generation to [emit
+   a .NET class that implements the interface as a proxy to the JS object](
+   https://github.com/microsoft/node-api-dotnet/blob/main/src/NodeApi.DotNetHost/JSInterfaceMarshaller.cs).
+   AOT modules should not export APIs that expect an interface to be implemented by JS.