Merge pull request #36 from teogor/docs/deployment

Introduce MkDocs for documentation generation

.github/CODEOWNERS

@@ -0,0 +1,16 @@
+# Lines starting with '#' are comments.
+# Each line is a file pattern followed by one or more owners.
+
+# More details are here: https://help.github.com/articles/about-codeowners/
+
+# The '*' pattern is global owners.
+# Not adding in this PR, but I'd like to try adding a global owner set with the entire team.
+# One interpretation of their docs is that global owners are added only if not removed
+# by a more local rule.
+
+# Order is important. The last matching pattern has the most precedence.
+# The folders are ordered as follows:
+
+# In each subsection folders are ordered first by depth, then alphabetically.
+# This should make it easy to add new rules without breaking existing ones.
+*       @teogor

.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: [ teogor ]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/publish-docs.yml

@@ -0,0 +1,134 @@
+name: Publish API Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+  pull-requests: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "api-docs"
+  cancel-in-progress: false
+
+env:
+  OWNER: teogor
+  DESTINATION_BRANCH: docs/teogor/${{ github.event.repository.name }}/${{ github.sha }}
+  REPOSITORY: ${{ github.event.repository.name }}
+  REPO: teogor/${{ github.event.repository.name }}
+  DISPLAY_NAME: Sudoklify
+
+jobs:
+  synchronize-documentation:
+    runs-on: ubuntu-latest
+    name: Synchronize Repository Documentation
+    steps:
+      - uses: actions/checkout@v4
+
+      # Grants execute permission to gradle (safety step)
+      - name: Grant Permissions to gradlew
+        run: chmod +x gradlew
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material
+          pip install mkdocs-material[recommended,git,imaging]
+
+      - name: Build MkDocs
+        run: |
+          mkdocs build --clean
+          mkdocs --version
+
+      - name: Setup Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Generate API Documentation
+        run: ./gradlew -D'org.gradle.unsafe.configuration-cache=false' dokkaHtmlMultiModule
+
+      - name: Relocate API References
+        run: |
+          mkdir -p build/docs/${{ env.REPOSITORY }}/reference
+          cp -r build/dokka/htmlMultiModule/* build/docs/${{ env.REPOSITORY }}/reference
+
+      - id: publish-docs
+        name: Deploy Documentation
+        uses: ./.github/workflows/sync-docs/
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+        with:
+          source-file: build/docs/${{ env.REPOSITORY }}/
+          destination-folder: ${{ env.REPOSITORY }}
+          destination-repo: teogor/source.teogor.dev
+          user-email: open-source@teogor.dev
+          user-name: Teodor Grigor
+          destination-branch-create: ${{ env.DESTINATION_BRANCH }}
+
+  build-and-deploy:
+    needs: synchronize-documentation
+    name: Build and Deploy Updated API Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout other repository
+        uses: actions/checkout@v3
+        with:
+          repository: teogor/source.teogor.dev
+          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          ref: ${{ env.DESTINATION_BRANCH || 'main' }}
+          # This is important to fetch the changes to the previous commit
+          fetch-depth: 0
+
+#      - name: Prettify code
+#        uses: creyD/prettier_action@v4.3
+#        with:
+#          # This part is also where you can pass other options, for example:
+#          prettier_options: --write ${{ env.REPOSITORY }}/**/*.{js,html,css,json}
+#          only_changed: False
+#          same_commit: True
+
+      - name: Create PR (Pull Request)
+        run: |
+          json=$(curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.PERSONAL_ACCESS_TOKEN }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/teogor/source.teogor.dev/pulls \
+            -d '{
+              "title":"Updated documentation for `${{ env.REPO }}`",
+              "body":"## 🚀 **Updated Documentation for ${{ env.DISPLAY_NAME }}** 🚀\n\nThis pull request brings you the latest updates to the [${{ env.DISPLAY_NAME }}](https://github.com/${{ env.REPO }}) documentation, ensuring you have access to the most comprehensive and informative guide for using this powerful library.\n\n-------\n\n* Generated by [Publish Docs](https://github.com/${{ env.REPO }}/actions/workflows/publish-docs.yml)\n\n* From [${{ env.REPO }}](https://github.com/${{ env.REPO }})",
+              "head":"${{ env.DESTINATION_BRANCH }}",
+              "base":"main"
+            }' | jq .)
+
+          number=$(jq '.number' <<< ${json})
+
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.PERSONAL_ACCESS_TOKEN }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/teogor/source.teogor.dev/issues/${number}/labels \
+            -d '{"labels":["@documentation"]}'
+
+          curl -L \
+            -X PUT \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.PERSONAL_ACCESS_TOKEN }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/teogor/source.teogor.dev/pulls/${number}/merge \

.github/workflows/sync-docs/action.yml

@@ -0,0 +1,65 @@
+name: 'Publish Docs'
+description: 'Comprehensive publish docs'
+branding:
+  icon: 'git-commit'
+  color: 'red'
+inputs:
+  source-file:
+    description: 'Source file from the origin directory'
+    required: true
+  destination-repo:
+    description: 'Destination repository'
+    required: true
+  destination-folder:
+    description: 'Directory to push the file to'
+    required: false
+  user-email:
+    description: 'Email for the git commit'
+    required: true
+  user-name:
+    description: 'GitHub username for the commit'
+    required: true
+  destination-branch:
+    description: 'branch to push file to, defaults to main'
+    required: false
+  destination-branch-create:
+    description: 'Destination branch to create for this commit'
+    required: false
+  commit-message:
+    description: 'A custom message for the commit'
+    required: false
+  rename:
+    description: 'Rename the destination file'
+    required: false
+  use-rsync:
+    description: 'Copy files/directories using rsync instead of cp. Experimental feature, please know your use case'
+    required: false
+  git-server:
+    description: 'Git server host, default github.com'
+    required: false
+    default: github.com
+runs:
+  using: "composite"
+  steps:
+    - name: Make all .sh files executable
+      run: find . -type f -name "*.sh" -exec chmod +x {} \;
+      shell: bash
+
+    - run: echo "${{ github.action_path }}" >> $GITHUB_PATH
+      shell: bash
+
+    - name: Execute Entrypoint Script
+      shell: bash
+      env:
+        SOURCE_FILE: ${{ inputs.source-file }}
+        DESTINATION_REPO: ${{ inputs.destination-repo }}
+        DESTINATION_FOLDER: ${{ inputs.destination-folder }}
+        USER_EMAIL: ${{ inputs.user-email }}
+        USER_NAME: ${{ inputs.user-name }}
+        DESTINATION_BRANCH: ${{ inputs.destination-branch }}
+        DESTINATION_BRANCH_CREATE: ${{ inputs.destination-branch-create }}
+        COMMIT_MESSAGE: ${{ inputs.commit-message }}
+        GIT_SERVER: ${{ inputs.git-server }}
+        RENAME: ${{ inputs.rename }}
+        USE_RSYNC: ${{ inputs.use-rsync }}
+      run: sync-files.sh

.github/workflows/sync-docs/sync-files.sh

@@ -0,0 +1,78 @@
+#!/bin/sh
+
+set -e
+set -x
+
+# Validate required input
+if [ -z "$SOURCE_FILE" ]; then
+  echo "Error: Source file must be specified."
+  exit 1
+fi
+
+# Set default values for optional variables
+if [ -z "$GIT_SERVER" ]; then
+  GIT_SERVER="github.com"
+fi
+
+if [ -z "$DESTINATION_BRANCH" ]; then
+  DESTINATION_BRANCH="main"
+fi
+
+# Clone the destination Git repository
+OUTPUT_BRANCH="$DESTINATION_BRANCH"
+
+CLONE_DIR=$(mktemp -d)
+echo "Cloning destination Git repository: $DESTINATION_REPO"
+
+git config --global user.email "$USER_EMAIL"
+git config --global user.name "$USER_NAME"
+
+git clone --single-branch --branch $DESTINATION_BRANCH "https://x-access-token:$API_TOKEN_GITHUB@$GIT_SERVER/$DESTINATION_REPO.git" "$CLONE_DIR"
+
+# Determine the destination file path
+DEST_COPY="$CLONE_DIR/$DESTINATION_FOLDER/"
+
+if [ ! -z "$RENAME" ]; then
+  echo "Renaming file to: ${RENAME}"
+  DEST_COPY="$CLONE_DIR/$DESTINATION_FOLDER/$RENAME"
+fi
+
+# Delete the previous folder if it exists
+if [ -d "$DEST_COPY" ]; then
+  echo "Deleting existing folder: $DEST_COPY"
+  rm -rf "$DEST_COPY"
+fi
+
+# Copy the source file to the destination repository
+echo "Copying contents to Git repo: $SOURCE_FILE"
+
+# Move the source file instead of copying it to avoid creating duplicates
+cp -r "$SOURCE_FILE" "$DEST_COPY"
+
+# Check out the specified branch or create a new one
+cd "$CLONE_DIR"
+
+if [ ! -z "$DESTINATION_BRANCH_CREATE" ]; then
+  echo "Creating new branch: $DESTINATION_BRANCH_CREATE"
+  git checkout -b "$DESTINATION_BRANCH_CREATE"
+  OUTPUT_BRANCH="$DESTINATION_BRANCH_CREATE"
+fi
+
+if [ -z "$COMMIT_MESSAGE" ]; then
+  COMMIT_MESSAGE="Automated updates based on https://$GIT_SERVER/${GITHUB_REPOSITORY}/commit/${GITHUB_SHA}"
+fi
+
+# Add the copied file to the staging area
+echo "Adding git commit"
+git add .
+
+# Commit changes if there are any
+if git status | grep -q "Changes to be committed"; then
+  echo "Committing changes with message: $COMMIT_MESSAGE"
+  git commit --message "$COMMIT_MESSAGE"
+
+  echo "Pushing git commit to branch: $OUTPUT_BRANCH"
+  git push -u origin HEAD:"$OUTPUT_BRANCH"
+else
+  echo "No changes detected, skipping commit and push"
+fi