Feat/auto generated docs

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Docs Workflow
+
+on:
+  push:
+    branches:
+      - main
+      - feat/generated-docs
+      - feat/auto-generated-docs
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup dotnet 6.0
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: "6.0.x"
+
+      - name: Pre-build script
+        working-directory: ./docs
+        run: sh pre-build.sh
+
+      - run: dotnet tool update -g docfx
+
+      - run: docfx docs/docfx.json
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_site

README.md

@@ -7,14 +7,13 @@ The official SurrealDB library for .NET.
 [![](https://img.shields.io/badge/license-Apache_License_2.0-00bfff.svg?style=flat-square)](https://github.com/surrealdb/surrealdb.net)
 [![](https://img.shields.io/nuget/v/surrealdb.net?style=flat-square)](https://www.nuget.org/packages/SurrealDb.Net)
 
-
 ⚠️ This driver is currently community maintained.
 
 ## Getting started
 
 ### Installation
 
-```
+```bash
 dotnet add package SurrealDb.Net
 ```
 
@@ -264,13 +263,13 @@ Unit/Integration tests are written using [xUnit](https://xunit.net/) and [Fluent
 
 You will need a local SurrealDB instance alongside the tests. Start one using the following command:
 
-```
+```bash
 surreal start --log debug --user root --pass root memory --auth --allow-guests
 ```
 
 Once ready, go to the root directory of the project and run the following command:
 
-```
+```bash
 dotnet watch test --project SurrealDb.Net.Tests
 ```
 
@@ -280,12 +279,28 @@ This project also contains [benchmarks](https://benchmarkdotnet.org/) in order t
 
 You will need a local SurrealDB instance alongside the tests. Start one using the following command:
 
-```
+```bash
 surreal start --log debug --user root --pass root memory --auth --allow-guests
 ```
 
 Once ready, go to the root directory of the project and run the following command:
 
-```
+```bash
 dotnet run -c Release --project SurrealDb.Net.Benchmarks --filter '*'
 ```
+
+### Documentation
+
+The documentation website of this project is automatically generated using [docfx](https://dotnet.github.io/docfx/).
+
+If you want to contribute to the documentation, be sure to have .NET SDK on your computer (.NET 6.0 or higher) and then install the cli tool:
+
+```bash
+dotnet tool update -g docfx
+```
+
+Then run the following command to start the web server:
+
+```bash
+docfx docs\docfx.json --serve
+```

docs/.gitignore

@@ -0,0 +1,11 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site
+
+index.md

docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/docfx.json

@@ -0,0 +1,58 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": ["**/SurrealDb.Net.csproj"],
+          "src": "../"
+        }
+      ],
+      "dest": "api",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "nested",
+      "memberLayout": "separatePages",
+      "EnumSortOrder": "alphabetic",
+      "allowCompilationErrors": false,
+      "properties": {
+        "TargetFramework": "net6.0"
+      }
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": ["api/**.yml", "api/index.md"]
+      },
+      {
+        "files": ["articles/**.md", "articles/**/toc.yml", "toc.yml", "*.md"]
+      }
+    ],
+    "resource": [
+      {
+        "files": ["images/**"]
+      }
+    ],
+    "output": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": ["default", "templates/surrealdb"],
+    "postProcessors": [],
+    "keepFileLink": false,
+    "disableGitFeatures": false,
+    "globalMetadata": {
+      "_appName": "SurrealDB .NET SDK",
+      "_appTitle": "The official SurrealDB library for .NET",
+      "_appFaviconPath": "images/favicon.ico",
+      "_appLogoPath": "images/logo.png",
+      "_appFooter": "",
+      "_enableSearch": true,
+      "_disableSideFilter": false,
+      "_enableNewTab": true,
+      "_disableContribution": false,
+      "_disableBreadcrumb": false
+    }
+  }
+}

docs/pre-build.sh

@@ -0,0 +1 @@
+cp ../README.md index.md

docs/templates/surrealdb/layout/_master.tmpl

@@ -0,0 +1,72 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+{{!include(/^styles/.*/)}}
+{{!include(/^fonts/.*/)}}
+{{!include(favicon.ico)}}
+{{!include(logo.svg)}}
+{{!include(search-stopwords.json)}}
+<!DOCTYPE html>
+<!--[if IE]><![endif]-->
+<html>
+    {{>partials/head}}
+
+    <body>
+        <div class="top-navbar">
+            <a class="burger-icon" onclick="toggleMenu()">
+                <svg name="Hamburger" 
+                    style="vertical-align: middle;"
+                    width="34" height="34" viewBox="0 0 24 24"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M20 6H4V9H20V6ZM4 10.999H20V13.999H4V10.999ZM4 15.999H20V18.999H4V15.999Z"></path></svg>
+            </a>
+
+            {{>partials/logo}}
+        </div>
+
+        <div class="body-content">
+            <div id="blackout" class="blackout" onclick="toggleMenu()"></div>
+
+            <nav id="sidebar" role="navigation">
+                <div class="sidebar">
+                    {{>partials/navbar}}
+                    <div class="sidebar-item-separator"></div>
+                    {{^_disableToc}}
+                        {{>partials/toc}}
+                    {{/_disableToc}}
+                </div>
+                {{>partials/footer}}
+            </nav>
+
+            <main class="main-panel">
+                {{#_enableSearch}}
+                {{>partials/searchResults}}
+                {{/_enableSearch}}
+
+
+
+                <div role="main" class="hide-when-search" >
+                    {{^_disableBreadcrumb}}
+                        {{>partials/breadcrumb}}
+                    {{/_disableBreadcrumb}}
+
+                   {{^_disableContribution}}
+                         <div id="contribution">
+                             {{#docurl}}
+                               <a href="{{docurl}}" class="contribution-link">{{__global.improveThisDoc}}</a>
+                             {{/docurl}}
+                         </div>
+                    {{/_disableContribution}}
+
+                    <article class="content wrap" id="_content" data-uid="{{uid}}">
+                      {{!body}}
+                    </article>
+                </div>
+
+                {{#_copyrightFooter}}
+                <div class="copyright-footer">
+                    <span>{{_copyrightFooter}}</span>
+                </div>
+                {{/_copyrightFooter}}
+            </main>
+        </div>
+
+        {{>partials/scripts}}
+    </body>
+</html>

docs/templates/surrealdb/partials/footer.tmpl.partial

@@ -0,0 +1,4 @@
+<div class="footer">
+  {{{_appFooter}}}
+  {{^_appFooter}}<strong><a href='https://dotnet.github.io/docfx/'>DocFX</a> + <a href='https://www.singulink.com'>Singulink</a> = ♥</strong>{{/_appFooter}}
+</div>

docs/templates/surrealdb/partials/head.tmpl.partial

@@ -0,0 +1,24 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+  <title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
+  <meta name="viewport" content="width=device-width">
+  <meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
+  <meta name="generator" content="docfx {{_docfxVersion}}">
+  {{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
+  <link rel="shortcut icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
+  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/night-owl.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.css" integrity="sha384-EvBWSlnoFgZlXJvpzS+MAUEjvN7+gcCwH+qh7GRFOGgZO0PuwOFro7qPOJnLfe7l" crossorigin="anonymous">
+  <link rel="stylesheet" href="{{_rel}}styles/config.css">
+  <link rel="stylesheet" href="{{_rel}}styles/discord.css">
+  <link rel="stylesheet" href="{{_rel}}styles/singulink.css">
+  <link rel="stylesheet" href="{{_rel}}styles/main.css">
+  <meta property="docfx:navrel" content="{{_navRel}}">
+  <meta property="docfx:tocrel" content="{{_tocRel}}">
+  {{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
+  {{#_enableSearch}}<meta property="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
+  {{#_enableNewTab}}<meta property="docfx:newtab" content="true">{{/_enableNewTab}}
+</head>

docs/templates/surrealdb/partials/li.tmpl.partial

@@ -0,0 +1,31 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<ul class="nav level{{level}}">
+  {{#items}}
+    {{^dropdown}}
+      <li>
+          {{^leaf}}
+            <span class="expand-stub"></span>
+          {{/leaf}}
+          {{#topicHref}}
+            <a href="{{topicHref}}" class="sidebar-item" name="{{tocHref}}" title="{{name}}">{{name}}</a>
+          {{/topicHref}}
+          {{^topicHref}}
+            <a>{{{name}}}</a>
+          {{/topicHref}}
+
+        {{^leaf}}
+          {{>partials/li}}
+        {{/leaf}}
+      </li>
+    {{/dropdown}}
+    {{#dropdown}}
+      <li class="dropdown">
+        <a class="dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">{{name}} <span class="caret"></span></a>
+        <ul class="dropdown-menu level{{level}}">
+          {{>partials/dd-li}}
+        </ul>
+      </li>
+    {{/dropdown}}
+  {{/items}}
+</ul>

docs/templates/surrealdb/partials/logo.tmpl.partial

@@ -0,0 +1,9 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<a class="brand" href="{{_rel}}index.html">
+  <img src="{{_rel}}{{{_appLogoPath}}}{{^_appLogoPath}}logo.svg{{/_appLogoPath}}" alt="" class="logomark">
+  <div class="brand-title">
+    <span>.NET SDK for</span>
+    <img inline src="{{_rel}}images/surrealdb.svg" alt="SurrealDB" class="brand-title-img" />
+  </div>
+</a>

docs/templates/surrealdb/partials/namespace.tmpl.partial

@@ -0,0 +1,13 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<h1 id="{{id}}" data-uid="{{uid}}" class="text-break">{{>partials/title}}</h1>
+<div class="markdown level0 summary">{{{summary}}}</div>
+<div class="markdown level0 conceptual">{{{conceptual}}}</div>
+<div class="markdown level0 remarks">{{{remarks}}}</div>
+{{#children}}
+  <h3 id="{{id}}">{{>partials/namespaceSubtitle}}</h3>
+  {{#children}}
+    <h5><xref uid="{{uid}}" altProperty="fullName" displayProperty="name"/></h5>
+    <section>{{{summary}}}</section>
+  {{/children}}
+{{/children}}

docs/templates/surrealdb/partials/navbar.tmpl.partial

@@ -0,0 +1,19 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<div>
+  <div class="mobile-hide">
+    {{>partials/logo}}
+  </div>
+
+  {{#_enableSearch}}
+  <div class="sidesearch">
+    <form id="search" role="search" class="search">
+        <i class="bi bi-search search-icon"></i>
+        <input type="text" id="search-query" placeholder="{{__global.search}}" autocomplete="off">
+    </form>
+  </div>
+  {{/_enableSearch}}
+
+  <div id="navbar">
+  </div>
+</div>