ci: implement robust wiki sync with link transformation and sidebar

.gitea/workflows/documentation.yml

@@ -8,6 +8,9 @@ on:
 jobs:
   generate-docs:
     runs-on: ubuntu-latest
+    permissions:
+      wiki: write
+      contents: write
     steps:
       - name: Checkout Code
         uses: actions/checkout@v3
@@ -24,56 +27,62 @@ jobs:
           ./gradlew dokkaGfm
 
       - name: Sync to Wiki
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_ACTOR: ${{ github.actor }}
         run: |
-          git config --global user.name "Gitea Bot"
-          git config --global user.email "bot@gitea.io"
+          git config --global user.name "Gitea Actions"
+          git config --global user.email "actions@gitea.io"
           
-          WIKI_URL="https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@gitea.archvium.eu/KrzysztofC/Retro_HA.wiki.git"
+          WIKI_URL="https://x-access-token:${{ secrets.GITEA_TOKEN }}@gitea.archvium.eu/KrzysztofC/Retro_HA.wiki.git"
           
-          # Jeśli repozytorium jest puste, clone może zwrócić błąd, więc robimy fallback
-          git clone "$WIKI_URL" wiki_dir || (mkdir wiki_dir && cd wiki_dir && git init && git remote add origin "$WIKI_URL" && cd ..)
+          # Clone the wiki repository
+          git clone "$WIKI_URL" wiki_dir
           
-          # Usuwamy stare pliki (oprócz .git)
+          # Clean up old files except .git
           find wiki_dir -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
           
-          # Kopiujemy nowe pliki ze standardowej lokalizacji Dokka MultiModule (jeśli istnieje)
-          # lub z pojedynczych modułów
+          # Copy new documentation files
+          # Check for multi-module output or fallback to individual modules
           if [ -d "build/dokka/gfm" ]; then
             cp -r build/dokka/gfm/* wiki_dir/
           else
-            # Fallback dla pojedynczych modułów
-            cp -r shared/build/dokka/gfm/* wiki_dir/ 2>/dev/null || true
-            cp -r app/build/dokka/gfm/* wiki_dir/ 2>/dev/null || true
+            [ -d "shared/build/dokka/gfm" ] && cp -r shared/build/dokka/gfm/* wiki_dir/
+            [ -d "app/build/dokka/gfm" ] && cp -r app/build/dokka/gfm/* wiki_dir/
           fi
           
           cd wiki_dir
           
-          # Gitea Wiki źle radzi sobie z linkami zawierającymi rozszerzenie .md w URL.
-          # Usuwamy .md z linków wewnętrznych za pomocą Perla (pomijamy linki http/https).
-          find . -type f -name "*.md" -exec perl -pi -e 's/\]\((?!http)(.*?)\.md(?:#(.*?))?\)/\]\($1#$2\)/g' {} +
-          # Sprzątanie pustych anchorów (jeśli #$2 było puste, zostaje '#' na końcu, usuwamy to)
+          # TRANSFORM LINKS FOR GITEA WIKI
+          # 1. Remove .md extension from all internal markdown links
+          # 2. Handle both [text](path.md) and [text](path.md#anchor)
+          # 3. Remove './' prefixes which confuse Gitea routing
+          find . -type f -name "*.md" -exec perl -pi -e 's/\]\((?!http)(\.?\/)?(.*?)\.md(?:#(.*?))?\)/\]\($2#$3\)/g' {} +
+          
+          # Clean up trailing '#' if no anchor was present
           find . -type f -name "*.md" -exec perl -pi -e 's/#\)/)/g' {} +
           
-          # Tworzymy statyczną stronę Home.md. 
-          # Kopiowanie index.md psuło linki relatywne, więc tworzymy prosty router.
-          echo "# RetroHA Developer Wiki" > Home.md
-          echo "Welcome to the autogenerated API documentation." >> Home.md
-          echo "" >> Home.md
-          if [ -d "shared" ]; then
-            echo "- [Shared Module API Reference](shared/index)" >> Home.md
-          fi
-          if [ -d "app" ]; then
-            echo "- [App Module API Reference](app/index)" >> Home.md
-          fi
+          # CREATE SIDEBAR FOR GLOBAL NAVIGATION
+          echo "### RetroHA API" > _Sidebar.md
+          echo "* [Home](Home)" >> _Sidebar.md
+          [ -d "shared" ] && echo "* [Shared Module](shared/index)" >> _Sidebar.md
+          [ -d "app" ] && echo "* [App Module](app/index)" >> _Sidebar.md
+          echo "" >> _Sidebar.md
+          echo "---" >> _Sidebar.md
+          echo "*Generated by Dokka*" >> _Sidebar.md
           
+          # CREATE HOME PAGE (ENTRY POINT)
+          echo "# RetroHA Developer Wiki" > Home.md
+          echo "Welcome to the autogenerated technical documentation for the RetroHA project." >> Home.md
+          echo "" >> Home.md
+          echo "### Project Modules" >> Home.md
+          [ -f "shared/index.md" ] || [ -f "shared/index" ] && echo "* **[Shared Module](shared/index)**: Core data models and HA client logic." >> Home.md
+          [ -f "app/index.md" ] || [ -f "app/index" ] && echo "* **[App Module](app/index)**: Android application UI and Bauhaus Canvas engine." >> Home.md
+          echo "" >> Home.md
+          echo "---" >> Home.md
+          echo "Use the sidebar on the right to navigate between packages and classes." >> Home.md
+          
+          # COMMIT AND PUSH
           git add .
           if ! git diff --cached --quiet; then
-            git commit -m "docs: auto-update wiki from CI/CD"
-            
-            # Wypychamy na gałąź 'main', skoro Gitea ustawiła ją jako domyślną.
+            git commit -m "docs: sync transformed documentation to gitea wiki"
             git branch -M main
             git push -u origin main --force
           else