docs: implemented typedoc + vitepress documentation (#333)

.github/workflows/docs.yaml

@@ -0,0 +1,54 @@
+name: Build and Push Docs
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  dockerize:
+    runs-on: ubuntu-latest
+    container:
+      image: docker:dind
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Get Docker meta (for tags)
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: |
+            ${{ vars.DOCKER_REGISTRY }}/${{ vars.DOCKER_DOCS_TAG }}
+          tags: |
+            type=schedule
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v2
+        with:
+          registry: ${{ vars.DOCKER_REGISTRY }}
+          username: ${{ secrets.SVC_GH_SUDOSOS_USERNAME }}
+          password: ${{ secrets.SVC_GH_SUDOSOS_PWD }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Build and push
+        uses: docker/build-push-action@v3
+        with:
+          context: .
+          file: ./Dockerfile-docs
+          platforms: linux/amd64
+          push: ${{ github.event_name == 'push' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -18,3 +18,6 @@ config
 data/
 
 .env
+/docs/.vitepress/cache/
+/docs/.vitepress/dist/
+/docs/content/typedoc/

Dockerfile-docs

@@ -0,0 +1,33 @@
+FROM node:20-alpine AS typedoc-builder
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+COPY ./ ./
+COPY tsconfig.json ./
+
+RUN npm run typedoc
+
+FROM node:20-alpine AS vitepress-builder
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY ./docs/ ./docs
+COPY --from=typedoc-builder /app/docs/content/typedoc/ ./docs/content/typedoc/
+
+RUN npm run docs:build
+
+FROM nginx:stable-alpine AS final-stage
+
+RUN rm /etc/nginx/conf.d/default.conf
+COPY docs/nginx.conf /etc/nginx/conf.d/default.conf
+
+WORKDIR /app
+COPY --from=vitepress-builder /app/docs/.vitepress/dist /app
+
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

docs/.vitepress/config.mts

@@ -0,0 +1,43 @@
+import { defineConfig } from 'vitepress'
+import typedocSidebar from '../content/typedoc/typedoc-sidebar.json'
+
+const apiItems = typedocSidebar.filter((item: any) => !['helpers', 'internal', 'gewis'].includes(item.text.toLowerCase()));
+const internalsItems = typedocSidebar.filter((item: any) => ['helpers', 'internal', 'gewis'].includes(item.text.toLowerCase()));
+
+export default defineConfig({
+  title: "SudoSOS Backend",
+  srcDir: "./content",
+  base: "/docs/",
+  description: "Documentation, reference and examples for the SudoSOS Backend",
+
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Documentation', link: '/documentation' },
+      { text: 'Swagger', link: 'https://sudosos.gewis.nl/api/api-docs/'},
+    ],
+    search: {
+      provider: 'local'
+    },
+    sidebar: [
+      {
+        text: 'General',
+        items: [
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: '.env', link: '/env-variables' },
+        ],
+      },
+      {
+        text: 'Documentation',
+        items: [{text: 'Introduction', link: '/documentation'}, ...apiItems],
+      },
+      {
+        text: 'Internals',
+        items: [{text: "TypeDoc", link: '/typedoc'}, ...internalsItems],
+      }
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/gewis/sudosos-backend' },
+    ],
+  },
+})

docs/content/documentation.md

@@ -0,0 +1,9 @@
+# The SudoSOS Backend Documentation
+
+## Introduction
+
+Welcome to the SudoSOS Backend documentation! Here, you will find comprehensive information regarding the various entities and modules available in SudoSOS. Each entity or module has a dedicated page, which serves to explain the purpose, functionality, and usage of the entity.
+
+## Swagger API Documentation
+
+If you are looking for the Swagger documentation, you can find it [here](https://sudosos.gewis.nl/api/api-docs/). This resource provides detailed API specifications and examples to help you integrate with the SudoSOS backend effectively.

docs/content/getting-started.md

@@ -0,0 +1 @@
+This page will contain information on how to get started with developing for the SudoSOS backend.

docs/content/index.md

@@ -0,0 +1,45 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "SudoSOS Backend"
+  text: "Documentation, references and examples"
+  tagline: Made with <3 by the ApplicatieBeheerCommissie
+  image:
+    src: /hero.png
+    link: https://github.com/GEWIS/sudosos-frontend/blob/develop/apps/dashboard/src/assets/img/bier.png
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started
+    - theme: alt
+      text: Documentation
+      link: /documentation
+    - theme: alt
+      text: GitHub
+      link: https://github.com/GEWIS/sudosos-backend
+
+features:
+  - title: Swagger API Documentation
+    icon:
+      src: /swagger.svg
+      alt: Swagger
+    details: Explore the Swagger API documentation to interact with and understand the SudoSOS backend API. Test endpoints and review request/response structures live.
+    link: https://sudosos.gewis.nl/api/api-docs/
+
+  - title: SudoSOS Dashboard
+    icon:
+      src: /hero.png
+      alt: Dashboard
+    details: Go to the SudoSOS Dashboard and view it in action.
+    link: https://sudosos.gewis.nl/
+
+  - title: Backend GitHub Repository
+    icon: 
+      src: github-mark.png
+      alt: GitHub
+    details: View the source code, contribute, and explore ongoing development of the SudoSOS Backend on GitHub. Open issues or submit pull requests to collaborate.
+    link: https://github.com/GEWIS/sudosos-backend
+---
+

docs/content/markdown-examples.md

@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````md
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

docs/content/typedoc.md

@@ -0,0 +1,47 @@
+# Documentation Workflow
+
+This document explains the process we use to generate the SudoSOS Backend documentation. Our workflow leverages several tools to produce clear, user-friendly documentation. The key tools we use include:
+
+- [**TypeDoc**](https://typedoc.org/)
+- [**typedoc-plugin-merge-modules**](https://github.com/krisztianb/typedoc-plugin-merge-modules)
+- [**typedoc-plugin-markdown**](https://www.npmjs.com/package/typedoc-plugin-markdown)
+- [**typedoc-vitepress-theme**](https://www.typedoc-plugin-markdown.org/plugins/vitepress)
+
+These tools work together to create a seamless and navigable documentation site.
+
+## Best Practices
+
+When adding a new file to the codebase, ensure you include a `@module` JSDoc comment at the top. This comment defines the module that the file belongs to and helps keep the documentation organized.
+
+If you're creating a new entity or module, add a `@mergeTarget` JSDoc comment at the top of the file. This tag defines the main text that will be displayed in the documentation. It's recommended to place the `@mergeTarget` comment within the entity definition file, as these files tend to be smaller and less frequently updated, making them easier to maintain.
+
+::: danger
+**Important**: If a file is created without a `@module` JSDoc comment, the TypeDoc generator may place it in an unintended location, which can cause confusion.
+:::
+
+Modules intended for internal use should be moved to the `internal/` namespace to distinguish them from public-facing documentation.
+
+When submitting a pull request (PR), ensure you are gradually adding documentation. This incremental approach allows us to improve the documentation in manageable steps.
+
+## TypeDoc with `typedoc-plugin-merge-modules`
+
+**TypeDoc** generates documentation directly from TypeScript code, enabling us to maintain accurate and up-to-date docs. To improve navigability, we use the `typedoc-plugin-merge-modules`. This plugin consolidates multiple modules into a single, cohesive module, making the documentation easier to browse.
+
+Our code structure differs from the layout we want in the documentation. The `typedoc-plugin-merge-modules` helps us reorganize and group related modules.
+
+- The **first** `@module` tag in each file determines which module it belongs to in the documentation.
+- The `@mergeTarget` tag designates which text will appear when a user navigates to a module in the documentation.
+
+This setup ensures that the generated documentation is intuitive and reflects how the modules interact within the codebase.
+
+---
+
+### `typedoc-vitepress-theme` and `typedoc-plugin-markdown`
+
+We use **typedoc-plugin-markdown** to convert the TypeDoc output into Markdown format. This format is then integrated into **VitePress**, the tool we use to generate our documentation site.
+
+The VitePress configuration is straightforward. Most of the custom settings are defined in the `.vitepress/config.mts` file. By using this setup, we can efficiently generate and maintain a clean, navigable documentation site.
+
+---
+
+By adhering to these guidelines and making use of the tools mentioned, we can maintain high-quality documentation that is easy to navigate and continuously updated as the codebase evolves.

docs/nginx.conf

@@ -0,0 +1,29 @@
+server {
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+
+    listen 80;
+    server_name _;
+    index index.html;
+
+    location / {
+        # content location
+        root /app;
+
+        # exact matches -> reverse clean urls -> folders -> not found
+        try_files $uri $uri.html $uri/ =404;
+
+        # non existent pages
+        error_page 404 /404.html;
+
+        # a folder without index.html raises 403 in this setup
+        error_page 403 /404.html;
+
+        # adjust caching headers
+        # files in the assets folder have hashes filenames
+        location ~* ^/assets/ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+    }
+}