Use the PHP doc builder instead of Sphinx in CI

.gitattributes

@@ -1,4 +1,4 @@
-/doc/** export-ignore
-/extra/** export-ignore
-/tests export-ignore
+/doc/ export-ignore
+/extra/ export-ignore
+/tests/ export-ignore
 /phpunit.xml.dist export-ignore

.github/workflows/documentation.yml

@@ -4,7 +4,8 @@ on:
     pull_request:
     push:
         branches:
-            - '1.x'
+            - '2.x'
+            - '3.x'
 
 permissions:
   contents: read
@@ -19,32 +20,32 @@ jobs:
             -   name: "Checkout code"
                 uses: actions/checkout@v2
 
-            -   name: "Set up Python 3.7"
-                uses: actions/setup-python@v1
+            -   name: "Set-up PHP"
+                uses: shivammathur/setup-php@v2
                 with:
-                    python-version: '3.7' # Semantic version range syntax or exact version of a Python version
+                    php-version: 8.1
+                    coverage: none
+                    tools: "composer:v2"
 
-            -   name: "Display Python version"
-                run: python -c "import sys; print(sys.version)"
+            -   name: Get composer cache directory
+                id: composercache
+                working-directory: doc/_build
+                run: echo "::set-output name=dir::$(composer config cache-files-dir)"
 
-            -   name: "Install Sphinx dependencies"
-                run: sudo apt-get install python-dev build-essential
-
-            -   name: "Cache pip"
+            -   name: Cache dependencies
                 uses: actions/cache@v2
                 with:
-                    path: ~/.cache/pip
-                    key: ${{ runner.os }}-pip-${{ hashFiles('_build/.requirements.txt') }}
-                    restore-keys: |
-                        ${{ runner.os }}-pip-
-
-            -   name: "Install Sphinx + requirements via pip"
-                working-directory: "doc"
-                run: pip install -r _build/.requirements.txt
-
-            -   name: "Build documentation"
-                working-directory: "doc"
-                run: make -C _build SPHINXOPTS="-nqW -j auto" html
+                    path: ${{ steps.composercache.outputs.dir }}
+                    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+                    restore-keys: ${{ runner.os }}-composer-
+
+            -   name: "Install dependencies"
+                working-directory: doc/_build
+                run: composer install --prefer-dist --no-progress
+
+            -   name: "Build the docs"
+                working-directory: doc/_build
+                run: php build.php --disable-cache
 
     doctor-rst:
         name: "DOCtor-RST"

.gitignore

@@ -1,3 +1,5 @@
+/doc/_build/vendor
+/doc/_build/output
 /composer.lock
 /phpunit.xml
 /vendor

doc/_build/build.php

@@ -0,0 +1,56 @@
+#!/usr/bin/env php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
+use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use SymfonyDocsBuilder\BuildConfig;
+use SymfonyDocsBuilder\DocBuilder;
+
+(new Application('Twig docs Builder', '1.0'))
+    ->register('build-docs')
+    ->addOption('disable-cache', null, InputOption::VALUE_NONE, 'Use this option to force a full regeneration of all doc contents')
+    ->setCode(function (InputInterface $input, OutputInterface $output) {
+        $io = new SymfonyStyle($input, $output);
+        $io->text('Building all Twig docs...');
+
+        $outputDir = __DIR__.'/output';
+        $buildConfig = (new BuildConfig())
+            ->setContentDir(__DIR__.'/..')
+            ->setOutputDir($outputDir)
+            ->setImagesDir(__DIR__.'/output/_images')
+            ->setImagesPublicPrefix('_images')
+            ->setTheme('rtd')
+        ;
+
+        $buildConfig->setExcludedPaths(['vendor/']);
+        $buildConfig->disableJsonFileGeneration();
+        $buildConfig->disableBuildCache();
+
+        $result = (new DocBuilder())->build($buildConfig);
+
+        if ($result->isSuccessful()) {
+            // fix assets URLs to make them absolute (otherwise, they don't work in subdirectories)
+            foreach (glob($outputDir.'/**/*.html') as $htmlFilePath) {
+                $htmlContents = file_get_contents($htmlFilePath);
+                file_put_contents($htmlFilePath, str_replace('href="assets/', 'href="/assets/', $htmlContents));
+            }
+
+            $io->success(sprintf('The Twig docs were successfully built at %s', realpath($outputDir)));
+        } else {
+            $io->error(sprintf("There were some errors while building the docs:\n\n%s\n", $result->getErrorTrace()));
+            $io->newLine();
+            $io->comment('Tip: you can add the -v, -vv or -vvv flags to this command to get debug information.');
+
+            return 1;
+        }
+
+        return 0;
+    })
+    ->getApplication()
+    ->setDefaultCommand('build-docs', true)
+    ->run();

doc/_build/composer.json

@@ -0,0 +1,19 @@
+{
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "config": {
+        "platform": {
+            "php": "8.1.0"
+        },
+        "preferred-install": {
+            "*": "dist"
+        },
+        "sort-packages": true
+    },
+    "require": {
+        "php": ">=8.1",
+        "symfony/console": "^5.4",
+        "symfony/process": "^5.4",
+        "symfony-tools/docs-builder": "^0.18"
+    }
+}