Automate docs generation

.github/workflows/generate-docs.yml

@@ -0,0 +1,128 @@
+name: Plugin Documentation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  generate_docs:
+    name: 'Generate documentation'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          # Fetch history for all branches and tags to allow for successful merge of base branch if needed.
+          fetch-depth: 0
+
+      - name: Determine branch names
+        id: branches
+        run: |
+          BASE_BRANCH=${GITHUB_REF#refs/heads/}
+          echo "::set-output name=base::$(echo "$BASE_BRANCH")"
+          echo "::set-output name=head::$(echo "update/docs-$BASE_BRANCH")"
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '7.4'
+
+      - name: Get Composer Cache Directory
+        id: composer-cache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Configure Composer cache
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-composer-
+
+      - name: Install Composer dependencies
+        run: composer install --prefer-dist --optimize-autoloader --no-progress --no-interaction
+
+      - name: Setup WordPress
+        run: |
+          docker-compose up -d
+
+          echo "::group::Get environment vars from containers"
+          MYSQL_PWD=$(docker-compose exec -T mysql printenv MYSQL_ROOT_PASSWORD)
+          WORDPRESS_DB_NAME=$(docker-compose exec -T wordpress printenv WORDPRESS_DB_NAME)
+          HOST_PORT=$(docker-compose port wordpress 80 | awk -F : '{printf $2}')
+          echo "::endgroup::"
+
+          echo "::group::Wait for database container to be ready"
+          echo -en "Waiting for database connection..."
+          until $(docker-compose exec -T wordpress bash -c "echo -n > /dev/tcp/mysql/3306" >/dev/null 2>&1); do
+              echo -n '.'
+              sleep 5
+          done
+          echo ''
+          echo "::endgroup::"
+
+          echo "::group::Installing WordPress"
+          docker-compose exec -T -e MYSQL_PWD="$MYSQL_PWD" mysql mysql -e "CREATE DATABASE IF NOT EXISTS $WORDPRESS_DB_NAME"
+          docker-compose exec -T cli wp core install \
+            --title="Docs" --admin_user=admin --admin_password=password [email protected] --skip-email --url=http://localhost:$HOST_PORT
+          echo "::endgroup::"
+
+          echo "::group::Activate AMP plugin"
+          # Building the JS assets is required for the plugin to activate successfully, but since we're only generating
+          # the docs we simply create the file being checked for to save some time.
+          touch ../../assets/js/amp-block-editor.js
+          docker-compose exec -T cli wp plugin activate amp
+          echo "::endgroup::"
+        working-directory: bin/local-env
+
+      - name: Configure git user
+        run: |
+          git config user.email "[email protected]"
+          git config user.name "Pierre Gordon"
+
+      - name: Check if remote branch exists
+        id: remote-branch
+        run: echo ::set-output name=exists::$([[ -z $(git ls-remote --heads origin "$HEAD_BRANCH" ) ]] && echo "0" || echo "1")
+        env:
+          HEAD_BRANCH: ${{ steps.branches.outputs.head }}
+
+      - name: Create branch to base pull request on
+        if: steps.remote-branch.outputs.exists == 0
+        run: git checkout -b "$HEAD_BRANCH"
+        env:
+          HEAD_BRANCH: ${{ steps.branches.outputs.head }}
+
+      - name: Fetch existing branch to add commits to
+        if: steps.remote-branch.outputs.exists == 1
+        run: |
+          git checkout "$HEAD_BRANCH"
+          git merge --no-edit "$BASE_BRANCH"
+        env:
+          BASE_BRANCH: ${{ steps.branches.outputs.base }}
+          HEAD_BRANCH: ${{ steps.branches.outputs.head }}
+
+      - name: Generate plugin documentation
+        run: docker-compose exec -T -u $(id --user) cli wp amp docs generate
+        working-directory: bin/local-env
+
+      - name: Check if there are changes
+        id: changes
+        run: echo ::set-output name=changed::$([[ -z $(git status --porcelain) ]] && echo "0" || echo "1")
+
+      - name: Commit and push changes
+        if: steps.changes.outputs.changed == 1
+        run: |
+          git add --all .
+          git commit -m "Update documentation"
+          git push origin "$HEAD_BRANCH"
+        env:
+          HEAD_BRANCH: ${{ steps.branches.outputs.head }}
+
+      - name: Create pull request
+        if: steps.changes.outputs.changed == 1 && steps.remote-branch.outputs.exists == 0
+        run: |
+          git push -u origin "$HEAD_BRANCH"
+          gh pr create --base "$BASE_BRANCH" --title "Update documentation for \`$BASE_BRANCH\` branch" --body "" --label Documentation
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BASE_BRANCH: ${{ steps.branches.outputs.base }}
+          HEAD_BRANCH: ${{ steps.branches.outputs.head }}

docs/src/Parser/Parser.php

@@ -87,7 +87,6 @@ public function parse_files( $files, $root ) {
 			$out = [
 				'file' => $this->export_docblock( $file ),
 				'path' => str_replace( DIRECTORY_SEPARATOR, '/', $file->getFilename() ),
-				'root' => $root,
 			];
 
 			if ( ! empty( $file->uses ) ) {