ionide · TheAngryByrd · Sep 12, 2023 · Sep 11, 2023 · Sep 12, 2023 · Sep 12, 2023
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
@@ -7,6 +7,12 @@
       "commands": [
         "fantomas"
       ]
+    },
+    "fsdocs-tool": {
+      "version": "19.0.0",
+      "commands": [
+        "fsdocs"
+      ]
     }
   }
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -8,6 +8,11 @@ on:
     branches:
       - master
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   ci:
 
@@ -21,3 +26,18 @@ jobs:
 
       - name: Build
         run: dotnet fsi build.fsx
+
+      - name: Upload documentation
+        if: github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./output
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: ci
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
diff --git a/.gitignore b/.gitignore
@@ -549,4 +549,9 @@ FodyWeavers.xsd
 ### VisualStudio Patch ###
 # Additional files built by Visual Studio
 
-# End of https://www.toptal.com/developers/gitignore/api/visualstudio,visualstudiocode,rider,macos,windows,rider
+# End of https://www.toptal.com/developers/gitignore/api/visualstudio,visualstudiocode,rider,macos,windows,rider
+
+# fsdocs
+tmp
+.fsdocs
+output
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -10,6 +10,12 @@
     <OtherFlags>$(OtherFlags) --test:GraphBasedChecking --test:ParallelOptimization --test:ParallelIlxGen</OtherFlags>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <FsDocsLicenseLink>https://github.com/ionide/FSharp.Analyzers.SDK/blob/master/LICENSE.md</FsDocsLicenseLink>
+    <FsDocsReleaseNotesLink>https://github.com/ionide/FSharp.Analyzers.SDK/blob/master/CHANGELOG.md</FsDocsReleaseNotesLink>
+    <RepositoryUrl>https://github.com/ionide/FSharp.Analyzers.SDK</RepositoryUrl>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="DotNet.ReproducibleBuilds" PrivateAssets="All" />
     <Content Include="$(MSBuildThisFileDirectory)README.md" PackagePath="README.md" />

diff --git a/build.fsx b/build.fsx
@@ -20,6 +20,9 @@ pipeline "Build" {
         run
             "dotnet run --project src/FSharp.Analyzers.Cli/FSharp.Analyzers.Cli.fsproj -- --project ./samples/OptionAnalyzer/OptionAnalyzer.fsproj --analyzers-path ./samples/OptionAnalyzer/bin/Release --verbose"
     }
+    stage "docs" {
+        run "dotnet fsdocs build --properties Configuration=Release --eval --nodefaultcontent --clean --strict"
+    }
     runIfOnlySpecified false
 }
 
@@ -29,4 +32,11 @@ pipeline "ReleaseBuild" {
     runIfOnlySpecified true
 }
 
+pipeline "Docs" {
+    restoreStage
+    buildStage
+    stage "fsdocs" { run "dotnet fsdocs watch --properties Configuration=Release --eval" }
+    runIfOnlySpecified true
+}
+
 tryPrintPipelineCommandHelp ()
diff --git a/docs/_template.html b/docs/_template.html
@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html lang="en" data-root="{{root}}">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <meta name="author" content="{{fsdocs-authors}}">
+    <title>{{fsdocs-page-title}} | {{fsdocs-collection-name}}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fira+Code&display=swap" rel="stylesheet">
+    <script src="https://code.iconify.design/iconify-icon/1.0.7/iconify-icon.min.js"></script>
+    <link rel="icon" type="image/png" sizes="32x32" href="{{root}}images/favicon.png"/>
+    <link type="text/css" rel="stylesheet" href="{{root}}style.css"/>
+    {{fsdocs-watch-script}}
+</head>
+
+<body>
+<header>
+    <div class="start">
+        <iconify-icon class="toggle menu-icon" icon="lucide:menu" width="24" height="24"></iconify-icon>
+        <a href="{{root}}">
+            <img src="{{root}}/images/logo.png" alt="FSharp.Analyzers.SDK logo"/>
+        </a>
+        <strong>FSharp.Analyzers.SDK</strong>
+        <div id="search-input" class="search">
+            <iconify-icon icon="carbon:search" width="16" height="16"></iconify-icon>
+            <em>Search the docs...</em>
+            <iconify-icon icon="iconoir:slash" width="16" height="16"></iconify-icon>
+        </div>
+    </div>
+    <div class="end">
+        <a href="{{fsdocs-repository-link}}" target="_blank">
+            <iconify-icon icon="uil:github" width="24" height="24"></iconify-icon>
+        </a>
+        <iconify-icon icon="carbon:search" class="search" width="24" height="24"></iconify-icon>
+        <iconify-icon class="themeToggle light" icon="ion:moon-sharp" width="24" height="24"></iconify-icon>
+        <iconify-icon class="themeToggle dark" icon="clarity:sun-solid" width="24" height="24"></iconify-icon>
+    </div>
+
+</header>
+<aside>
+    <div class="close">
+        <iconify-icon icon="ei:close" class="menu-icon" width="32" height="32"></iconify-icon>
+    </div>
+    <div class="content">
+        {{fsdocs-list-of-documents}}
+        {{fsdocs-list-of-namespaces}}
+    </div>
+</aside>
+<main>
+    <div id="fsdocs-content">
+        {{fsdocs-content}}
+        {{fsdocs-tooltips}}
+    </div>
+</main>
+<script type="module">
+    document.querySelector("header .toggle").addEventListener("click", () => {
+        document.querySelector("aside").classList.toggle("open");
+    })
+
+    document.querySelector("aside .menu-icon").addEventListener("click", () => {
+        document.querySelector("aside").classList.toggle("open");
+    });
+
+    const prefersDark = window.matchMedia("@media (prefers-color-scheme: dark)").matches;
+    let currentTheme = localStorage.getItem('theme') ?? (prefersDark ? 'dark' : 'light');
+
+    const setTheme = theme => {
+        currentTheme = theme;
+        document.documentElement.setAttribute("data-theme", theme);
+        localStorage.setItem("theme", theme);
+    }
+    // set initial theme
+    setTheme(currentTheme);
+    const toggles = [ ...document.querySelectorAll(".themeToggle") ];
+
+    toggles.forEach(toggle => {
+        toggle.addEventListener("click", () => {
+            const otherTheme = currentTheme === "light" ? "dark" : "light";
+            setTheme(otherTheme);
+        });
+    });
+
+    [...document.querySelectorAll(".search")].forEach(search => {
+        search.addEventListener("click", () => {
+            window.alert("This should trigger the algolia thing and is not yet implemented");
+        });
+    })
+</script>
+<script type="module" src="{{root}}tooltips.js"></script>
+<script type="module" src="{{root}}copyCommand.js"></script>
+</body>
+</html>
diff --git a/docs/content/Getting Started.fsx b/docs/content/Getting Started.fsx
@@ -0,0 +1,74 @@
+(**
+---
+category: end-users
+categoryindex: 1
+index: 1
+---
+
+# Getting started
+
+## Create project
+
+Create a new class library targeting `net6.0`
+
+```shell
+dotnet new classlib -lang F# -f net6.0 -n OptionValueAnalyzer
+```
+
+Note that the assembly name needs to contain `Analyzer` in the name in order for it to be picked up.
+
+Add a reference to the analyzers SDK:
+
+```shell
+dotnet add package FSharp.Analyzers.SDK
+```
+
+```shell
+paket add FSharp.Analyzers.SDK
+```
+
+## First analyzer
+
+An [Analyzer](../reference/fsharp-analyzers-sdk-analyzer.html) is a function that takes a `Context` and returns a list of `Message`.
+*)
+
+(*** hide ***)
+#r "../../src/FSharp.Analyzers.Cli/bin/Release/net6.0/FSharp.Analyzers.SDK.dll"
+#r "../../src/FSharp.Analyzers.Cli/bin/Release/net6.0/FSharp.Compiler.Service.dll"
+(** *)
+
+module OptionAnalyzer =
+
+    open FSharp.Analyzers.SDK
+
+    // This attribute is required!
+    [<Analyzer>]
+    let optionValueAnalyzer: Analyzer =
+        fun (context: Context) ->
+            // inspect context to determine the error/warning messages
+            // A potential implementation might traverse the untyped syntax tree
+            // to find any references of `Option.Value`
+            [
+                {
+                    Type = "Option.Value analyzer"
+                    Message = "Option.Value shouldn't be used"
+                    Code = "OV001"
+                    Severity = Warning
+                    Range = FSharp.Compiler.Text.Range.Zero
+                    Fixes = []
+                }
+            ]
+
+(**
+## Running your first analyzer
+
+After building your project you can run your analyzer on a project of your choosing using the [fsharp-analyzers](https://www.nuget.org/packages/fsharp-analyzers) tool.
+
+```shell
+dotnet tool install --global fsharp-analyzers
+```
+
+```shell
+fsharp-analyzers --project YourProject.fsproj --analyzers-path ./OptionAnalyzer/bin/Release --verbose
+```
+*)
diff --git a/docs/copyCommand.js b/docs/copyCommand.js
@@ -0,0 +1,51 @@
+import {LitElement, html, css} from 'https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js';
+import copy from 'https://esm.sh/[email protected]';
+
+export class CopyCommandButton extends LitElement {
+    static properties = {
+        content: {type: String, attribute: true},
+        clicked: {type: Boolean, state: true}
+    }
+
+    constructor() {
+        super();
+        this.clicked = false;
+    }
+
+    static styles = css`
+      iconify-icon {
+        cursor: pointer;
+      }
+    `
+
+    onClick() {
+        copy(this.content);
+        this.clicked = true;
+        setTimeout( () => {
+            this.clicked = false;
+        }, 500);
+    }
+
+    render() {
+        return this.clicked ? html`
+            <iconify-icon icon="ic:twotone-check" width="16" height="16"></iconify-icon>` : html`
+            <iconify-icon icon="solar:clipboard-outline" width="16" height="16" @click=${this.onClick}></iconify-icon>`;
+    }
+}
+
+customElements.define('copy-icon', CopyCommandButton);
+
+const codeToCopy = [...document.querySelectorAll("code[lang=shell],code[lang=bash]")];
+codeToCopy.forEach(code => {
+    const copyIcon = document.createElement("copy-icon");
+    copyIcon.setAttribute("content", code.textContent);
+    const wrapInTd = element => { const td = document.createElement("td"); td.append(element); return td }
+    const row = code.parentElement.parentElement.parentElement;
+    row.append(wrapInTd(copyIcon));
+
+    const terminalIcon = document.createElement("iconify-icon");
+    terminalIcon.setAttribute("icon", "ph:terminal-bold");
+    terminalIcon.setAttribute("width", "16");
+    terminalIcon.setAttribute("height", "16");
+    row.prepend(wrapInTd(terminalIcon));
+});
diff --git a/docs/images/favicon.png b/docs/images/favicon.png
diff --git a/docs/images/logo.png b/docs/images/logo.png