chore: add the doc template (#15)

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @arttet

.github/workflows/gh-pages.yml

@@ -0,0 +1,58 @@
+name: GitHub Pages
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    env:
+      ZOLA_VERSION: 0.19.2
+      DOC_DIR: docs
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Setup Zola
+        run: |
+          curl -s -L https://github.com/getzola/zola/releases/download/v${{ env.ZOLA_VERSION }}/zola-v${{ env.ZOLA_VERSION }}-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin
+        shell: bash
+
+      - name: Build GitHub Pages
+        run: zola --root ${{ env.DOC_DIR }} build
+
+      - name: Upload artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./${{ env.DOC_DIR }}/public
+
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: build
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/github-ci.yml

@@ -31,7 +31,7 @@ jobs:
           goimports -e -l $(pwd)
 
       - name: Check Markdown format
-        uses: DavidAnson/markdownlint-cli2-action@v17
+        uses: DavidAnson/markdownlint-cli2-action@v17.0.0
         with:
           globs: '**/*.md'
 
@@ -83,7 +83,7 @@ jobs:
       - name: Test
         run: |
           go env -w CGO_ENABLED=1
-          go test -v -timeout 30s -race ./...
+          go test -v -timeout 30s -race -shuffle on ./...
 
   coverage:
     runs-on: ubuntu-latest
@@ -101,36 +101,44 @@ jobs:
       - name: Install requirements
         run: |
           go install github.com/jstemmer/go-junit-report@latest
+          go install github.com/jandelgado/gcov2lcov@latest
 
-      - name: Generate code coverage
+      - name: Generate the tests and code coverage reports
         run: |
           go env -w CGO_ENABLED=0
           go test ./... -v -coverprofile coverage.out
           go test ./... -v | go-junit-report > report.xml
           go tool cover -html coverage.out -o coverage.html
+          gcov2lcov -infile=coverage.out -outfile=coverage.lcov
 
-      - name: Upload the test results to Codecov
+      - name: Upload the test report to Codecov
         if: ${{ !cancelled() }}
         uses: codecov/test-results-action@v1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./report.xml
 
-      - name: Upload the code coverage results to Codecov
+      - name: Upload the code coverage report to Codecov
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.out
           flags: unittests
           name: codecov-umbrella
 
-      - name: Upload the code coverage results to GitHub
+      - name: Upload the code coverage report to Codacy
+        uses: codacy/[email protected]
+        with:
+          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+          coverage-reports: ./coverage.lcov
+
+      - name: Upload the code coverage report to GitHub
         uses: actions/upload-artifact@v4
         with:
           name: code-coverage-report
           path: coverage.html
 
-      - name: Trigger Go Report Card Refresh
+      - name: Refresh the Go Report card
         if: github.ref == 'refs/heads/main'
         run: |
-          curl -X POST https://goreportcard.com/report/github.com/${{ github.repository }}
+          curl -X POST -F "repo=github.com/${{ github.repository }}" https://goreportcard.com/checks

Makefile

@@ -9,6 +9,7 @@ LOCAL_PKG ?= github.com/arttet/Interview-Preparation-Kit-in-Go
 ################################################################################
 
 # Note: use Makefile.local for customization
+-include misc/make/doc.Makefile
 -include Makefile.local
 
 ## ▸▸▸ Development commands ◂◂◂

README.md

@@ -28,6 +28,10 @@ pprof:                  Run performance profiling with pprof
 coverage:               Generate an HTML report for code coverage
 validate:               Validate configurations
 clean:                  Remove generated build artifacts
+▸▸▸ Documentation commands ◂◂◂
+doc-build:              Build the documentation site [env: DOC_DIR=]
+doc-serve:              Serve the documentation site [env: DOC_PORT=]
+doc-clean:              Remove generated artifacts [env: DOC_DIR=]
 ```
 
 ## License

docs/.gitignore

@@ -0,0 +1 @@
+public

docs/config.toml

@@ -0,0 +1,16 @@
+# The URL the site will be built for
+base_url = "https://example.com"
+
+# Whether to automatically compile all Sass files in the sass directory
+compile_sass = true
+
+# Whether to build a search index to be used later on by a JavaScript library
+build_search_index = true
+
+[markdown]
+# Whether to do syntax highlighting
+# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
+highlight_code = true
+
+[extra]
+# Put all your custom variables here

go.mod

@@ -1,6 +1,6 @@
 module github.com/arttet/Interview-Preparation-Kit-in-Go
 
-go 1.23
+go 1.23.1
 
 require github.com/stretchr/testify v1.9.0
 

misc/make/doc.Makefile

@@ -0,0 +1,16 @@
+DOC_DIR ?= docs
+DOC_PORT ?= 2000
+
+## ▸▸▸ Documentation commands ◂◂◂
+
+.PHONY: doc-build
+doc-build:		## Build the documentation site [env: DOC_DIR=]
+	zola --root ${DOC_DIR} build
+
+.PHONY: doc-serve
+doc-serve:		## Serve the documentation site [env: DOC_PORT=]
+	zola --root ${DOC_DIR} serve --open
+
+.PHONY: doc-clean
+doc-clean:		## Remove generated artifacts [env: DOC_DIR=]
+	rm -rf ${DOC_DIR}/public