docs: add MkDocs Material site with stdlib API reference generator

Set up a documentation site using MkDocs Material that combines the
language specification, auto-generated stdlib API reference, tooling
docs, and the Blazor WASM playground under a single GitHub Pages
deployment.

- mkdocs.yml with full nav (112 spec pages, 35 stdlib pages, tooling)
- docs/index.md landing page
- build_tools/generate_stdlib_docs.py: regex-based C# parser that
  extracts XML doc comments from Sharpy.Core, mangles names to
  snake_case, maps C# types to Sharpy types, and generates markdown
- 35 generated stdlib pages (builtins, 5 core types, 28 modules)
- Unified docs.yml workflow replaces playground.yml (builds MkDocs +
  playground, combines into single site at /sharpy/)
- Fix broken links in function_types.md and type_casting.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: antonsynd

.github/workflows/playground.yml .github/workflows/docs.yml.github/workflows/playground.yml renamed to .github/workflows/docs.yml

@@ -1,13 +1,15 @@
-name: Deploy Playground
+name: Deploy Documentation
 
 on:
   push:
     branches: [ "mainline" ]
     paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
       - 'src/Sharpy.Playground/**'
       - 'src/Sharpy.Compiler/**'
       - 'src/Sharpy.Core/**'
-      - '.github/workflows/playground.yml'
+      - '.github/workflows/docs.yml'
   workflow_dispatch:
 
 permissions:
@@ -26,6 +28,19 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      # Build MkDocs site
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      # Build Blazor WASM playground
       - name: Setup .NET
         uses: actions/setup-dotnet@v5
         with:
@@ -35,15 +50,19 @@ jobs:
         run: dotnet workload install wasm-tools
 
       - name: Publish Playground
-        run: dotnet publish src/Sharpy.Playground/Sharpy.Playground.csproj -c Release -o release
+        run: dotnet publish src/Sharpy.Playground/Sharpy.Playground.csproj -c Release -o playground-release
+
+      - name: Rewrite base href for playground subdirectory
+        run: sed -i 's|<base href="/" />|<base href="/sharpy/playground/" />|g' playground-release/wwwroot/index.html
 
-      - name: Rewrite base href
-        run: sed -i 's|<base href="/" />|<base href="/sharpy/" />|g' release/wwwroot/index.html
+      # Combine into single site
+      - name: Copy playground into docs site
+        run: cp -r playground-release/wwwroot site/playground
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v4
         with:
-          path: release/wwwroot
+          path: site
 
   deploy:
     environment:

.gitignore

@@ -2,6 +2,9 @@ editors/vscode/out/
 
 mcp.json
 
+# MkDocs build output
+site/
+
 node_modules/
 .serena/
 

build_tools/cli.py

@@ -56,6 +56,7 @@
             cmd_logs as builder_logs,
         )
         from build_tools.sharpy_auto_builder.config import Config as BuilderConfig
+        from build_tools.generate_stdlib_docs import generate as stdlib_generate
     except ImportError:
         # Fallback to relative imports
         from .generate_code_walkthroughs import (
@@ -78,6 +79,7 @@
             cmd_logs as builder_logs,
         )
         from .sharpy_auto_builder.config import Config as BuilderConfig
+        from .generate_stdlib_docs import generate as stdlib_generate
 except ImportError as e:
     print(f"Error importing build tools: {e}", file=sys.stderr)
     print("Make sure you're running from the Sharpy project root", file=sys.stderr)
@@ -707,6 +709,60 @@ def build_logs(
         sys.exit(1)
 
 
+# ==============================================================================
+# Stdlib Documentation Commands
+# ==============================================================================
+
+
+@cli.group()
+def stdlib():
+    """Generate standard library API documentation."""
+    pass
+
+
+@stdlib.command(name="generate")
+@click.option(
+    "--source-dir",
+    "-s",
+    type=click.Path(exists=True, path_type=Path),
+    default="src/Sharpy.Core",
+    help="Path to Sharpy.Core source directory (default: src/Sharpy.Core)",
+)
+@click.option(
+    "--output-dir",
+    "-o",
+    type=click.Path(path_type=Path),
+    default="docs/stdlib",
+    help="Output directory for generated docs (default: docs/stdlib)",
+)
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Overwrite existing files (default: skip existing)",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Print progress information",
+)
+def stdlib_gen(source_dir: Path, output_dir: Path, force: bool, verbose: bool):
+    """Generate stdlib API reference pages from Sharpy.Core C# source."""
+    try:
+        generated = stdlib_generate(
+            source_dir=source_dir.resolve(),
+            output_dir=output_dir.resolve(),
+            force=force,
+            verbose=verbose,
+        )
+        if not verbose:
+            click.echo(f"Generated {len(generated)} files in {output_dir}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
 # ==============================================================================
 # Global Status Command
 # ==============================================================================