[WIP] Update phpdoc.moodledev.io to use phpDocumentor

.github/workflows/publish-apidocs.yml

@@ -1,59 +1,126 @@
-name: Generate API docs and publish to Github Pages
+# TODO:
+#  - Document all supported versions and redirect to latest // see notes at https://github.com/phpDocumentor/phpDocumentor/blob/master/tests/integration/phpDocumentor/Configuration/data/phpDocumentor3XMLWithMultipleVersions.xml
+
+# Generate API docs and publish to GitHub Pages at phpdoc.moodledev.io
+#
+# How it works:
+#   - Get phpdoc config into ./
+#   - Get Moodle code into ./source
+#   - Setup cache at ./phpdoc-cache
+#   - Build docs into ./docs
+#   - Publish that to phpdoc.moodledev.io
+
+name: Generate phpdoc.moodledev.io
 
 env:
   BRANCHLIST: "MOODLE_401_STABLE MOODLE_402_STABLE MOODLE_403_STABLE main"
   VERSIONLIST: "4.1 4.2 4.3 main"
 
+# Allow GITHUB_TOKEN to deploy to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 on:
   schedule:
-    # Publish every Sunday at 1:30am
+    # Publish every Sunday at 00:30 UTC
     - cron: '30 1 * *  0'
   workflow_dispatch:
+  push:
+#TODO: update this when merging to moodle/phpdoc to only be main  
+    branches: ["main", "phpDocumentor"]  
 
 jobs:
-  deploy:
-    runs-on: ubuntu-20.04
+  build:
+    runs-on: ubuntu-latest
     concurrency:
       group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          show-progress: ''
+      - name: Checkout moodle/phpdoc
+        uses: actions/checkout@v4
 
-      - name: Checkout Moodle
+      - name: Checkout moodle/moodle
         uses: actions/checkout@v4
         with:
           repository: moodle/moodle
-          path: .moodle
-          show-progress: ''
+          path: source
+
+      # Install phpDocumentator using PHIVE
+      # phpDocumentator recommends PHIVE as the preferred install strategy
+      # Source: https://github.com/phpDocumentor/phpDocumentor/blob/919d5c1ef42a3c74d050e05ce99add6efa87b5a4/README.md?plain=1#L79
+      - name: Cache PHIVE tools
+        uses: actions/cache@v4
+        with:
+          path: ${{ runner.temp }}/.phive
+          key: php-phive-${{ hashFiles('.phive/phars.xml') }}
+          restore-keys: php-phive-
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
+      - name: Install PHIVE
+        uses: szepeviktor/phive@v1
         with:
-          node-version-file: '.moodle/.nvmrc'
+          home: ${{ runner.temp }}/.phive
+          binPath: ${{ github.workspace }}/tools/phive
+
+# TODO: confirm this is the correct GPG key
+# Blocker: https://github.com/phpDocumentor/phpDocumentor/issues/3694
+# TODO Maybe: specify a stable major branch of phpDocumentor to install rather than always getting latest release
+      - name: Install phpDocumentor
+        run: ${{ github.workspace }}/tools/phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42
 
-      - name: Build doxygen
-        run: docker build --tag=doxygen phpdocs/doxygen
+      - name: Cache phpDocumentor build files
+        id: phpdocumentor-cache
+        uses: actions/cache@v4
+        with:
+          path: phpdoc-cache
+          key: ${{ runner.os }}-phpdocumentor-${{ github.sha }}
+          restore-keys: ${{ runner.os }}-phpdocumentor-
 
-      - name: Generate all API Documentation
-        run: ./scripts/generate_api_docs.sh
+# TODO: remove the ignores below, they speed up the runs for quick evaluation while we're setting this up
+# Notice: -d xdebug.mode=off is required due to a bug/workaround
+# Issue: https://github.com/phpDocumentor/phpDocumentor/issues/3642#issuecomment-1912354577
+# See ignores implicitly loaded from phpdoc.dist.xml
+# excludes from https://github.com/moodle/phpdoc/blob/929083a815c1f7e95c540173e7549810f6d4a598/scripts/generate_phpdoc.sh#L27-L48
+      - name: Build with phpDocumentor
+        run: php -d xdebug.mode=off ${{ github.workspace }}/tools/phpDocumentor run -d source --target docs --cache-folder phpdoc-cache --template default --title 'Moodle PHP API'
 
-      - name: Copy Moodle Redirector
+      - name: Count files and get disk space
         run: |
-          mkdir -p build/master
-          cp redirect.html build/master/index.html
+          echo "Total files:"
+          find docs -type f | wc -l
+
+          echo "Total disk space used by docs directory:"
+          du -sh docs
+
+          echo "File list:"
+          find docs -type f
 
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Free disk space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./build
-          cname: phpdoc.moodledev.io
+          tool-cache: false
 
-      - name: Archive build ogs
-        if: always()
-        uses: actions/upload-artifact@v4
+      - name: Upload artifact to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
         with:
-          name: Build logs
-          path: logs
+          path: docs
+
+  deploy:
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,5 @@
-build
-Doxygen.*
-logs
+/source
+/docs
+/phpdoc-cache
+/.phive
+/tools

.phpdoc/template/base.html.twig

@@ -0,0 +1,8 @@
+{% extends 'layout.html.twig' %}
+
+{% set topMenu = {
+    "social": [
+        { "iconClass": "fab fa-github", "url": "https://github.com/moodle/moodle"},
+    ]
+}
+%}

.phpdoc/template/components/header-title.html.twig

@@ -0,0 +1,10 @@
+<h1 class="phpdocumentor-title">
+    <a href="{{ path('/') }}" class="phpdocumentor-title__link">
+      <svg width="123" height="31" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1230.87 315.18" aria-label="Moodle logo">
+        <path fill="#f98012" d="M289.61 309.77V201.51q0-33.94-28-33.95t-28.06 33.95v108.26H178.4V201.51q0-33.94-27.57-33.95-28.05 0-28 33.95v108.26H67.67V195.12q0-35.43 24.6-53.63 21.66-16.25 58.56-16.25 37.41 0 55.12 19.19 15.26-19.19 55.62-19.19 36.9 0 58.54 16.25 24.6 18.19 24.61 53.63v114.65Zm675.49-.5V0h55.16v309.27Zm-70.3 0v-18.22q-7.39 9.84-25.11 15.76a92.81 92.81 0 0 1-30.05 5.41q-39.4 0-63.28-27.09t-23.89-67c0-26.25 7.76-48.3 23.4-66 13.85-15.65 36.35-26.59 62.29-26.59 29.22 0 46.28 11 56.64 23.63V0h53.68v309.27Zm0-102.92q0-14.78-14-28.33T852 164.47q-21.16 0-33.48 17.24-10.85 15.3-10.84 37.43 0 21.68 10.84 36.94 12.3 17.75 33.48 17.73 12.81 0 27.83-12.07t15-24.86ZM648.57 314.19q-41.87 0-69.19-26.59T552 219.14q0-41.83 27.34-68.45t69.19-26.59q41.85 0 69.44 26.59t27.58 68.45q0 41.88-27.58 68.46t-69.4 26.59Zm0-145.77q-19.94 0-30.65 15.1t-10.71 35.88q0 20.78 10 35.13 11.46 16.34 31.4 16.32T680 254.53q10.46-14.34 10.46-35.13t-10-35.13q-11.46-15.86-31.89-15.85ZM449.13 314.19q-41.86 0-69.2-26.59t-27.33-68.46q0-41.83 27.33-68.45t69.2-26.59q41.83 0 69.44 26.59t27.57 68.45q0 41.88-27.57 68.46t-69.44 26.59Zm0-145.77q-19.94 0-30.66 15.1t-10.71 35.88q0 20.78 10 35.13 11.46 16.34 31.41 16.32t31.39-16.32Q491 240.19 491 219.4t-10-35.13q-11.44-15.86-31.87-15.85Zm636.45 67.47c1.18 13.13 18.25 41.37 46.31 41.37 27.31 0 40.23-15.77 40.87-22.16l58.11-.5c-6.34 19.39-32.1 60.58-100 60.58-28.24 0-54.08-8.79-72.64-26.35s-27.82-40.45-27.82-68.7q0-43.83 27.82-69.68t72.16-25.85q48.25 0 75.34 32 25.13 29.53 25.12 79.28Zm90.13-34c-2.3-11.83-7.23-21.49-14.77-29.06q-12.82-12.3-29.55-12.31-17.25 0-28.82 11.82t-15.5 29.55Z"/>
+        <path fill="#333" d="m174.74 116.9 54.74-40-.7-2.44C130 86.57 85.08 95.15 0 144.47l.79 2.24 6.76.07c-.62 6.81-1.7 23.64-.32 48.95-9.44 27.32-.24 45.88 8.4 66.07 1.37-21 1.23-44-5.22-66.89-1.35-25.14-.24-41.67.37-48.1l56.4.54a258 258 0 0 0 1.67 33.06c50.4 17.71 101.09-.06 128-43.72-7.47-8.37-22.11-19.79-22.11-19.79Z"/>
+      </svg>
+      <!-- {{ project.name }} -->
+      PHP API
+    </a>
+</h1>

.phpdoc/template/template.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<template>
+    <name>Moodle PHP API</name>
+    <author></author>
+    <email></email>
+    <version></version>
+    <extends></extends>
+    <transformations>
+        <transformation writer="twig" source="templates/default/index.html.twig" artifact="index2.html"/>
+    </transformations>
+</template>

README.md

@@ -1,3 +1,5 @@
 # Moodle API Documentation Generator
 
 PHPDoc is generated for all _supported_ major versions of Moodle.
+
+Website is published at https://phpdoc.moodledev.io.

phpdoc.dist.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpdocumentor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:noNamespaceSchemaLocation="https://www.phpdoc.org/phpDocumentor.xsd"
+               configVersion="3.0">
+
+    <title>Moodle PHP API</title>
+
+    <paths>
+        <output>docs</output>
+        <cache>phpdoc-cache</cache>
+    </paths>
+
+    <template name="default" />
+
+    <version number="4.3">
+        <folder>4.3</folder>
+        <api>
+            <source dsn=".">
+                <path>source</path>
+            </source>
+            <ignore>
+                <path>**/lib/pear/**/*</path>
+                <path>**/lib/google/**/*</path>
+                <path>**/lib/mlbackend/**/*</path>
+                <path>**/lib/**/*</path>
+                <path>**/tests/**/*</path>
+                <path>**/fixtures/**/*</path>
+                <path>**/vendor/**/*</path>
+                <path>**/amd/**/*</path>
+                <path>**/yui/**/*</path>
+                <path>**/lang/**/*</path>
+            </ignore>
+            <extensions>
+                <extension>php</extension>
+            </extensions>
+        </api>
+    </version>
+
+</phpdocumentor>