Full 3.0 site?

dotnet · Jan 4, 2025 · 014954e · 014954e
1 parent 534cf70
commit 014954e
Show file tree

Hide file tree

Showing 11 changed files with 288 additions and 41 deletions.
diff --git a/docs/for-contributors/README.md → docs/for-contributors/README.mdx b/docs/for-contributors/README.md → docs/for-contributors/README.mdx
@@ -1,3 +1,9 @@
+---
+title: "Overview"
+---
+
+import DocCardList from '@theme/DocCardList';
+
 # The Silk.NET Contributors Guide
 
 Welcome to the Silk.NET project! We're so glad you want to help us create the best native interoperation experience that
@@ -9,9 +15,9 @@ the codebase and hit the ground running.
 ## Table of Contents
 
 - [Getting Started (you are here!)](#getting-started)
+- [Contribution Process](../CONTRIBUTING.md)
 - [Build System](build-system.md)
 
-
 ## Getting Started
 
 ### Prerequisites
@@ -55,3 +61,4 @@ where the values for the `-s` arguments are replaced with the job names (the key
 For more information on SilkTocuh arguments, consult the [SilkTouch User Guide](../silktouch) or use
 `dotnet run --project sources/SilkTouch/SilkTouch/Silk.NET.SilkTouch.csproj -- --help`.
 
+<DocCardList />
diff --git a/docs/index.mdx b/docs/index.mdx
@@ -0,0 +1,77 @@
+---
+title: "Welcome"
+id: "index"
+description: 'Get Started with Silk.NET'
+slug: '/docs'
+---
+
+import DocCardList from '@theme/DocCardList';
+import { useDocsSidebar } from '@docusaurus/plugin-content-docs/client'
+
+# Welcome to Silk.NET!
+
+## Getting Started
+
+To get started, install the relevant NuGet packages. They add start with `Silk.NET`, and the next inner namespace after
+that indicates the binding or High-Level Utility (HLU, e.g. Windowing or Input) that package belongs. Here' some example
+commands to install such NuGet packages:
+
+```bash
+dotnet add package Silk.NET.Assimp
+dotnet add package Silk.NET.Input
+dotnet add package Silk.NET.Maths
+dotnet add package Silk.NET.Direct2D
+dotnet add package Silk.NET.Direct3D.Compilers
+dotnet add package Silk.NET.Direct3D9
+dotnet add package Silk.NET.Direct3D11
+dotnet add package Silk.NET.Direct3D12
+dotnet add package Silk.NET.DirectComposition
+dotnet add package Silk.NET.DirectStorage
+dotnet add package Silk.NET.DXGI
+dotnet add package Silk.NET.DXVA
+dotnet add package Silk.NET.XAudio
+dotnet add package Silk.NET.XInput
+dotnet add package Silk.NET.OpenAL
+dotnet add package Silk.NET.OpenCL
+dotnet add package Silk.NET.OpenGL
+dotnet add package Silk.NET.OpenGL.Legacy
+dotnet add package Silk.NET.OpenGLES
+dotnet add package Silk.NET.OpenXR
+dotnet add package Silk.NET.Shaderc
+dotnet add package Silk.NET.SPIRV.Cross
+dotnet add package Silk.NET.SPIRV.Reflect
+dotnet add package Silk.NET.Vulkan
+dotnet add package Silk.NET.WebGPU
+dotnet add package Silk.NET.Windowing
+```
+
+If you don't know which API you'd like to start with, try OpenGL if you'd like to draw graphics - it's an old but tested
+API that has universal compatibility on most platforms. It is succeeded by Vulkan, but there is a large jump in
+difficulty thereafter. Alternatively, if you only care about Microsoft platforms, try Direct3D 11! Note that the same
+caveat for Vulkan vs OpenGL applies to Direct3D 12 vs Direct3D 11.
+
+If you can't decide on one for now, we maintain a "metapackage" that pulls in most of Silk.NET's core packages from all
+bindings and High-Level Utilities (HLUs). You can install that as follows:
+
+```bash
+dotnet add package Silk.NET
+```
+
+As always, we're happy to help in our Discord server with whatever questions you have, no matter how far along you are!
+
+## Find Documentation
+
+Now that you've pulled in the APIs you would like to use, it's time to find documentation to follow. Most Silk.NET APIs
+(other than our High-Level Utilities) map 1:1 directly into a native API signature that should be easily searchable by
+its API name (e.g. `GL.GetString` becomes `glGetString`). Note that these rules are not consistent and it is expected
+that you have at least some familiarity with how the native API is structured.
+
+Of course, there are some bindings for which we have our own introductory documentation for, which presents a good
+jumping-off point for new users to Silk.NET - regardless of whether you've used the native API before (e.g. with C/C++)
+or you've never seen anything about it before! To that end, you can find our own documentation indexed below or
+throughout this site.
+
+<DocCardList items={useDocsSidebar().items} />
+
+Have fun! We always look forward to seeing what people can create with Silk.NET and would love to hear how you get on in
+our Discord server.
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
@@ -0,0 +1,84 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+const sidebars: SidebarsConfig = {
+    // By default, Docusaurus generates a sidebar from the docs folder structure
+    docsSidebar: [
+        "index",
+        {
+            type: 'category',
+            label: 'Vulkan Documentation',
+            link: {
+                type: "generated-index",
+            },
+            items: [
+                {
+                    type: 'autogenerated',
+                    dirName: 'vulkan'
+                },
+            ],
+        },
+        {
+            type: 'category',
+            label: 'Miscellaneous',
+            link: {
+                type: 'generated-index',
+                title: 'Miscellaneous',
+                description: 'This section of the website contains useful miscellaneous tidbits which we think will come in handy to get the most out of your Silk.NET application! It also contains other more general information pertaining to the project.',
+            },
+            items: [
+                {type: "doc", id: "CHANGELOG"},
+                {
+                    type: 'autogenerated',
+                    dirName: 'silk.net'
+                },
+                {type: "doc", id: "CODE_OF_CONDUCT"},
+            ],
+        },
+        {
+            type: 'category',
+            label: "Contributors",
+            link: {
+                type: "doc",
+                id: "for-contributors/README"
+            },
+            items: [
+                {
+                    type: "autogenerated",
+                    dirName: "for-contributors"
+                },
+                {
+                    type: "doc",
+                    id: "CONTRIBUTING",
+                    label: "Contribution Process"
+                }
+            ],
+        },
+    ],
+
+    // But you can create a sidebar manually
+    /*
+    tutorialSidebar: [
+      'intro',
+      'hello',
+      {
+        type: 'category',
+        label: 'Tutorial',
+        items: ['tutorial-basics/create-a-document'],
+      },
+    ],
+     */
+};
+
+export default sidebars;
diff --git a/docs/silk.net/deprecation-notices/README.md b/docs/silk.net/deprecation-notices/README.md
@@ -0,0 +1,23 @@
+# Deprecation Notices
+
+As time goes on we may deprecate certain features or APIs within Silk.NET if it becomes clear they are suboptimal and/or
+in need of replacement. We strive to post notices of such deprecations here, while also indicating a migration plan. If
+a deprecation is made and a notice is not posted here, it is possible that the deprecation was for a niche feature/API
+we didn't expect anyone to use anyway.
+
+Below are a list of deprecation notices for each major version. Note that the lack of a deprecation notice does not
+guarantee that there will be no incompatibilities between major versions - it should be taken for granted that you will
+encounter breaking changes even if the API that has been broken was not deprecated in the prior major version.
+
+## Silk.NET 1.X
+
+- [SilkManager](SilkManager.md)
+- [IVulkanView and related APIs](VulkanViews.md)
+
+## Silk.NET 2.X
+
+No deprecation notices have been posted for this major version.
+
+## Silk.NET 3.X
+
+No deprecation notices have been posted for this major version.
diff --git a/docs/silk.net/experimental-feed.md b/docs/silk.net/experimental-feed.md
@@ -0,0 +1,64 @@
+---
+{
+    "TableOfContents": {
+        "Name": "Experimental Feed",
+        "Url": "experimental-feed.html"
+    }
+}
+---
+
+# Experimental Feed
+
+> [!WARNING]
+> The experimental feed is not recommended for use for anything beyond playing around with the new features. We don't officially support these builds as they may be unstable, and should not be used in production.
+
+> [!NOTE]
+> Changes in the experimental feed happen rapidly. We recommend joining the [Silk.NET Discord server](https://discord.gg/DTHHXRt) so that you can keep up with development.
+
+## Configure your project
+
+Right now, your project should look something like this:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net7.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Silk.NET" Version="1.4.0" />
+  </ItemGroup>
+
+</Project>
+```
+
+In order to use the experimental feed, you must change this project file slightly. Add the following line to your project:
+
+```xml
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net7.0</TargetFramework>
+    <!-- Add the experimental feed as a restore source -->
+    <RestoreAdditionalProjectSources>$(RestoreAdditionalProjectSources);https://dotnet.github.io/Silk.NET/nuget/experimental/index.json</RestoreAdditionalProjectSources>
+  </PropertyGroup>
+```
+
+## Install an experimental version
+
+Now .NET has access to the experimental feed, it's time to install an experimental package. Check for the latest version on our [GitLab Package Registry](https://gitlab.com/silkdotnet/Silk.NET/-/packages).
+
+At the time of writing, the latest version is `2.0.0-build97.0`. Now to install this package, you can use your IDE's built-in NuGet client, `dotnet package add`, or just modify the project file again like so:
+
+```xml
+  <ItemGroup>
+    <PackageReference Include="Silk.NET" Version="2.0.0-build97.0" />
+  </ItemGroup>
+```
+
+
+> [!WARNING]
+> Experimental Feed builds may be deleted without warning at the Silk.NET team's discretion.
+
+Now you have access to bleeding-edge experimental builds of Silk.NET. Have fun!
diff --git a/docs/vulkan/structure-chaining/_category_.yml b/docs/vulkan/structure-chaining/_category_.yml
@@ -0,0 +1,3 @@
+link:
+  type: doc
+  id: overview
diff --git a/docs/vulkan/structure-chaining/overview.md b/docs/vulkan/structure-chaining/overview.md
@@ -1,4 +1,8 @@
-# Overview
+---
+title: Structure Chaining
+---
+
+# Overview
 
 ## Table of Contents
 
@@ -144,4 +148,4 @@ vk.GetPhysicalDeviceFeatures2(device, &features2);
 var depthBounds = features2.Features.DepthBounds;
 var runtimeDescriptorArray = indexingFeatures.RuntimeDescriptorArray;
 var accelerationStructure = accelerationStructureFeaturesKhr.AccelerationStructure;
-```
+```
diff --git a/sources/Website/docusaurus.config.ts b/sources/Website/docusaurus.config.ts
@@ -1,6 +1,7 @@
 import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
+import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";
 
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
@@ -37,14 +38,15 @@ const config: Config = {
             'classic',
             {
                 docs: {
-                    sidebarPath: './sidebars.ts',
+                    sidebarPath: '../../docs/sidebars.ts',
                     path: "../../docs",
                     routeBasePath: "docs",
                     // Please change this to your repo.
                     // Remove this to remove the "edit this page" links.
                     // editUrl:
                     //     'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
-                    exclude: ["README.md"]
+                    exclude: ["README.md"],
+                    beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives],
                 },
                 blog: {
                     showReadingTime: true,
@@ -75,7 +77,7 @@ const config: Config = {
             items: [
                 {
                     type: 'docSidebar',
-                    sidebarId: 'tutorialSidebar',
+                    sidebarId: 'docsSidebar',
                     position: 'left',
                     label: 'Documentation',
                 },

diff --git a/sources/Website/package-lock.json b/sources/Website/package-lock.json
diff --git a/sources/Website/package.json b/sources/Website/package.json
@@ -22,7 +22,8 @@
     "prism-react-renderer": "^2.3.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
-    "react-responsive-3d-carousel": "^2.1.1"
+    "react-responsive-3d-carousel": "^2.1.1",
+    "remark-github-admonitions-to-directives": "^2.1.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.6.3",