Merge pull request #8 from T-DAT-902-Homepedia/7-add-docker-container-and-github-workflow-automate-the-work-with-mdbook

Setup mdBook dev tools for docs writing

Author: glopez-dev

.github/workflows/mdbook-ci.yml

@@ -0,0 +1,55 @@
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'documentation/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Install mdbook-mermaid
+        run: cargo install mdbook-mermaid
+
+      - name: Build book
+        working-directory: ./documentation
+        run: mdbook build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./documentation/book
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Justfile

@@ -0,0 +1,27 @@
+default:
+    just --list
+
+up ENV:
+    #!/bin/bash
+    if [ "{{ENV}}" = "doc" ]; then
+    else
+        echo "{{ENV}}: Accepted values are: 'doc'." >&2
+    fi
+
+down ENV:
+    #!/bin/bash
+    if [ "{{ENV}}" = "doc" ]; then
+        docker compose -f docker/doc/compose.yml up --detach
+    else
+        echo "{{ENV}}: Accepted values are: 'doc'." >&2
+    fi
+
+logs ENV:
+    #!/bin/bash
+    if [ "{{ENV}}" = "doc" ]; then
+        docker compose -f docker/{{ENV}}/compose.yml logs --follow
+    else
+        echo "{{ENV}}: Accepted values are: 'doc'." >&2
+    fi
+
+

docker/doc/compose.yml

@@ -0,0 +1,14 @@
+services:
+  mdbook:
+    container_name: mdbook
+    image: peaceiris/mdbook:v0.5.0-rust
+    user: "${UID:-1000}:${GID:-1000}"
+    working_dir: /book
+    stdin_open: true
+    tty: true
+    ports:
+      - 3000:3000
+      - 3001:3001
+    volumes:
+      - ../../documentation:/book
+    command: serve --hostname 0.0.0.0

documentation/.gitignore

@@ -0,0 +1 @@
+book

documentation/book.toml

@@ -0,0 +1,14 @@
+[book]
+title = "Authentication Service"
+authors = ["Gabriel Lopez"]
+language = "en"
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output]
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

documentation/mermaid-init.js

@@ -0,0 +1,39 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();