Merge pull request #562 from SciSharp/docfx2

feat(docs): upgrade to DocFX v2 modern template

Author: Nucs

.github/workflows/docs.yml

@@ -4,7 +4,8 @@ on:
   push:
     branches: ["master", "main"]
     paths:
-      - 'docs/website/**'
+      - 'src/**'
+      - 'docs/website-src/**'
   workflow_dispatch:
 
 permissions:
@@ -17,7 +18,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  deploy:
+  build-and-deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
@@ -26,6 +27,23 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Install DocFX
+        run: dotnet tool install -g docfx
+
+      - name: Build docs
+        run: docfx docs/website-src/docfx.json
+
+      - name: Generate AI-friendly docs (llms.txt)
+        run: |
+          cd docs/website-src
+          chmod +x scripts/generate-llms-txt.sh
+          ./scripts/generate-llms-txt.sh ../website
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
 

docs/website-src/api/index.md

@@ -1,3 +1,38 @@
-# NumSharp docfx documentation
+---
+uid: api-index
+---
 
-This is the autogenerated documentation of NumSharp
+# NumSharp API Reference
+
+Browse the complete API documentation for NumSharp, including all classes, methods, and properties.
+
+## Namespaces
+
+- @NumSharp - Core types including `NDArray`, `Shape`, `np`
+- @NumSharp.Generic - Generic typed arrays like `NDArray<T>`
+- @NumSharp.Backends - Storage and computation backends
+
+## Key Types
+
+| Type | Description |
+|------|-------------|
+| @NumSharp.NDArray | The main multi-dimensional array type |
+| @NumSharp.Shape | Represents array dimensions and strides |
+| @NumSharp.np | Static API class for NumPy-style operations |
+| @NumSharp.Slice | Represents array slicing operations |
+
+## Getting Started
+
+```csharp
+using NumSharp;
+
+// Create arrays
+var a = np.array(new[] { 1, 2, 3, 4, 5 });
+var b = np.zeros((3, 4));
+var c = np.random.randn(2, 3);
+
+// Operations
+var sum = np.sum(a);
+var transposed = b.T;
+var sliced = a["1:4"];
+```

docs/website-src/docfx.json

@@ -1,65 +1,61 @@
 {
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
   "metadata": [
     {
       "src": [
         {
-          "src": "../../",
-          "files": [
-            "src/NumSharp.Core/NumSharp.Core.csproj"
-          ]
+          "src": "../../src",
+          "files": ["NumSharp.Core/NumSharp.Core.csproj"]
         }
       ],
       "dest": "api",
+      "includePrivateMembers": false,
       "disableGitFeatures": false,
-      "disableDefaultFilter": false
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "enumSortOrder": "declaringOrder",
+      "allowCompilationErrors": false
     }
   ],
   "build": {
     "content": [
       {
-        "files": [
-          "api/**.yml",
-          "api/index.md"
-        ]
-      },
-      {
-        "files": [
-          "articles/**.md",
-          "articles/**/toc.yml",
-          "toc.yml",
-          "*.md"
-        ]
+        "files": ["**/*.{md,yml}"],
+        "exclude": ["_site/**", "obj/**", "scripts/**", "filterConfig.yml", "templates/**"]
       }
     ],
     "resource": [
       {
-        "files": [
-          "images/**"
-        ]
+        "files": ["images/**"]
       }
     ],
-    "overwrite": [
-      {
-        "files": [
-          "apidoc/**.md"
-        ],
-        "exclude": [
-          "obj/**",
-          "_site/**"
-        ]
+    "output": "../website",
+    "template": ["default", "modern", "templates/numsharp"],
+    "globalMetadata": {
+      "_appName": "NumSharp",
+      "_appTitle": "NumSharp Documentation",
+      "_appLogoPath": "images/numsharp.icon.svg",
+      "_appFaviconPath": "images/numsharp.icon128.png",
+      "_appFooter": "<span>Copyright &copy; 2025 <a href='https://github.com/SciSharp'>SciSharp STACK</a>. Built with <a href='https://dotnet.github.io/docfx'>DocFX</a>.</span>",
+      "_enableSearch": true,
+      "_enableNewTab": true,
+      "_disableContribution": false,
+      "_disableNextArticle": false,
+      "_lang": "en",
+      "_gitContribute": {
+        "repo": "https://github.com/SciSharp/NumSharp",
+        "branch": "master"
       }
-    ],
-    "dest": "../website",
-    "globalMetadataFiles": [],
-    "fileMetadataFiles": [],
-    "template": [
-      "default"
-    ],
-    "postProcessors": [],
-    "markdownEngineName": "markdig",
-    "noLangKeyword": false,
-    "keepFileLink": false,
-    "cleanupCacheHistory": false,
-    "disableGitFeatures": false
+    },
+    "sitemap": {
+      "baseUrl": "https://scisharp.github.io/NumSharp",
+      "changefreq": "weekly",
+      "priority": 0.5
+    },
+    "xref": [],
+    "xrefService": ["https://xref.docs.microsoft.com/query?uid={uid}"],
+    "postProcessors": ["ExtractSearchIndex"]
   }
-}
+}

…website-src/articles/NDArray.Creation.md docs/website-src/docs/NDArray.Creation.mddocs/website-src/articles/NDArray.Creation.md renamed to docs/website-src/docs/NDArray.Creation.md docs/website-src/articles/NDArray.Creation.md renamed to docs/website-src/docs/NDArray.Creation.md

@@ -0,0 +1,40 @@
+# DocFX API Filter Configuration
+# https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis
+#
+# Uncomment rules below to hide internal/utility types from API documentation.
+# To enable: add "filter": "filterConfig.yml" to metadata section in docfx.json
+
+apiRules:
+  # Include all public APIs by default
+  - include:
+      hasAttribute:
+        uid: System.Runtime.CompilerServices.CompilerGeneratedAttribute
+      type: Member
+    exclude: true
+
+  # Uncomment to hide utility namespaces from public docs:
+  # - exclude:
+  #     uidRegex: ^NumSharp\.Utilities
+  #     type: Namespace
+
+  # - exclude:
+  #     uidRegex: ^NumSharp\.Backends\.Unmanaged\.Pooling
+  #     type: Namespace
+
+  # Uncomment to hide internal helper classes:
+  # - exclude:
+  #     uidRegex: Helper$
+  #     type: Class
+
+  # - exclude:
+  #     uidRegex: Extensions$
+  #     type: Class
+
+  # Uncomment to hide specific types:
+  # - exclude:
+  #     uidRegex: ^NumSharp\.Utilities\.InfoOf
+  #     type: Class
+
+  # - exclude:
+  #     uidRegex: ^NumSharp\.Utilities\.Converts
+  #     type: Class