docs: add initial docs (#54)

Co-authored-by: Raphael Strotz <Xzelsius@users.noreply.github.com>
Xzelsius · Sep 24, 2024 · 57e4f5c · 57e4f5c
1 parent 0f7772e
commit 57e4f5c
Show file tree

Hide file tree

Showing 34 changed files with 7,043 additions and 6 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -47,6 +47,14 @@ indent_size = 2
 indent_size = 2
 end_of_line = lf
 
+# JS and TS files
+[*.{js,ts}]
+indent_size = 2
+
+# CSS files
+[*.css]
+indent_size = 2
+
 # C# Source files
 [*.cs]
 indent_size = 4

diff --git a/.github/renovate.json b/.github/renovate.json
@@ -2,6 +2,7 @@
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
     "github>xzelsius/renovate-config:github-actions",
-    "github>xzelsius/renovate-config:dotnet"
+    "github>xzelsius/renovate-config:dotnet",
+    "github>xzelsius/renovate-config:npm"
   ]
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -14,7 +14,7 @@ env:
   NUGET_PACKAGES: '${{ github.workspace }}/.nuget/packages'
 
 jobs:
-  build:
+  build-packages:
     runs-on: ubuntu-latest
 
     steps:
@@ -59,9 +59,57 @@ jobs:
           path: ${{ github.workspace }}/artifacts/packages
           if-no-files-found: error
 
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+        with:
+          fetch-depth: 0
+
+      - name: NPM Cache
+        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/iron'
+
+      - name: NuGet Cache
+        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4
+        with:
+          path: |
+            ${{ env.NUGET_PACKAGES }}
+            .nuke/temp
+          key: ${{ runner.os }}-nuget-${{ hashFiles('**/global.json', '**/*.csproj', '**/*.props') }}
+          restore-keys: |
+            ${{ runner.os }}-nuget-
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@6bd8b7f7774af54e05809fcc5431931b3eb1ddee # v4
+
+      - name: Restore .NET Tools
+        run: |
+          dotnet tool restore
+
+      - name: Build Docs
+        run: |
+          dotnet nuke Docs
+
+      - name: Upload Docs
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ github.workspace }}/artifacts/docs
+
   publish-packages:
     runs-on: ubuntu-latest
-    needs: [build]
+    needs: [build-packages]
 
     # Only publish if build was triggered for a tag
     if: startsWith(github.ref, 'refs/tags/v')
@@ -91,3 +139,23 @@ jobs:
             --nuget-api-key $NUGET_API_KEY
         env:
           NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
+
+  publish-docs:
+    runs-on: ubuntu-latest
+    needs: [build-docs]
+
+    # Only publish if build was triggered for a tag
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      pages: write    # to deploy to pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+        id: deployment
diff --git a/.gitignore b/.gitignore
@@ -136,6 +136,12 @@ Icon
 .nuke/temp/
 artifacts/
 
+#================================
+# Docs
+#================================
+
+docs/.vitepress/cache
+
 #================================
 # Others
 #================================
diff --git a/.nuke/build.schema.json b/.nuke/build.schema.json
@@ -109,6 +109,7 @@
               "CreateAfterReleasePullRequest",
               "CreateRelease",
               "Default",
+              "Docs",
               "DotNetBuild",
               "DotNetPack",
               "DotNetPush",
@@ -119,7 +120,9 @@
               "Pack",
               "Publish",
               "ShipPublicApis",
-              "Test"
+              "Test",
+              "VitePressBuild",
+              "VitePressInstall"
             ]
           }
         },
@@ -141,6 +144,7 @@
               "CreateAfterReleasePullRequest",
               "CreateRelease",
               "Default",
+              "Docs",
               "DotNetBuild",
               "DotNetPack",
               "DotNetPush",
@@ -151,7 +155,9 @@
               "Pack",
               "Publish",
               "ShipPublicApis",
-              "Test"
+              "Test",
+              "VitePressBuild",
+              "VitePressInstall"
             ]
           }
         },

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitepress';
+import { shared } from './shared';
+import { en } from './en';
+
+export default defineConfig({
+  ...shared,
+  locales: {
+    root: { label: 'English', ...en },
+  },
+});
diff --git a/docs/.vitepress/en.ts b/docs/.vitepress/en.ts
@@ -0,0 +1,83 @@
+import { type DefaultTheme, defineConfig } from 'vitepress';
+
+export const en = defineConfig({
+  lang: 'en-US',
+  description: 'A lightweight development kit built to help developing applications using .NET',
+
+  themeConfig: {
+    nav: nav(),
+
+    sidebar: {
+      '/guide/': {
+        base: '/guide/',
+        items: guideSidebar(),
+      },
+      '/contributing/': {
+        base: '/contributing/',
+        items: contributingSidebar(),
+      },
+    },
+
+    editLink: {
+      pattern: 'https://github.com/Xzelsius/Ayaka/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © Raphael Strotz. All rights reserved.',
+    },
+  },
+});
+
+function nav(): DefaultTheme.NavItem[] {
+  return [
+    {
+      text: 'Guide',
+      link: '/guide/getting-started',
+      activeMatch: '/guide/',
+    },
+    {
+      text: 'Contributing',
+      link: '/contributing/sources',
+      activeMatch: '/contributing/',
+    },
+  ];
+}
+
+function guideSidebar(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Guide',
+      collapsed: false,
+      items: [
+        { text: 'Getting started', link: 'getting-started' },
+        { text: 'Packages', link: 'packages' },
+        { text: 'Compatibility', link: 'compatibility' },
+      ],
+    },
+  ];
+}
+
+function contributingSidebar(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Overview',
+      collapsed: false,
+      items: [
+        { text: 'Sources', link: 'sources' },
+        { text: 'Renovate', link: 'renovate' },
+      ],
+    },
+    {
+      text: 'Contributing',
+      collapsed: false,
+      items: [
+        { text: 'Code Guidelines', link: 'code-guidelines' },
+        { text: 'Bug Reports', link: 'bug-reports' },
+        { text: 'Feature Requests', link: 'feature-requests' },
+        { text: 'Pull Requests', link: 'pull-requests' },
+      ],
+    },
+  ];
+}
diff --git a/docs/.vitepress/shared.ts b/docs/.vitepress/shared.ts
@@ -0,0 +1,28 @@
+import { defineConfig } from 'vitepress';
+
+export const shared = defineConfig({
+  title: 'Ayaka',
+
+  base: '/ayaka/',
+
+  rewrites: {
+    'en/:rest*': ':rest*',
+  },
+
+  lastUpdated: true,
+  cleanUrls: true,
+  metaChunk: true,
+
+  themeConfig: {
+    logo: {
+      dark: '/logo-white.svg',
+      light: '/logo-black.svg',
+      width: 24,
+      height: 24,
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Xzelsius/Ayaka' },
+    ],
+  },
+});
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,6 @@
+:root {
+  --vp-c-brand-1: var(--vp-c-green-1);
+  --vp-c-brand-2: var(--vp-c-green-2);
+  --vp-c-brand-3: var(--vp-c-green-3);
+  --vp-c-brand-soft: var(--vp-c-green-soft);
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;
diff --git a/docs/en/contributing/bug-reports.md b/docs/en/contributing/bug-reports.md
@@ -0,0 +1,17 @@
+# Bug Reports
+
+A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!
+
+## Guidelines
+
+When creating a bug report, please follow these guidelines:
+
+1. Check if the issue has already been reported — [Issues]
+2. Check if the issue has been fixed — Try to reproduce it using the latest `main` branch
+3. Isolate the problem
+4. Submit using the `Bug report` template — [Submit a Bug report]
+
+A good bug report shouldn't leave other needing to chase you up for more information. Please try to be as detailed as possible in your report.
+
+[Issues]: https://github.com/Xzelsius/Ayaka/issues
+[Submit a bug report]: https://github.com/Xzelsius/Ayaka/issues/new?template=bug_report.yml