Allowed building dev version of the API references from Github Actions

Author: mnocon

.github/workflows/api_refs.yaml

@@ -4,9 +4,19 @@ on:
     workflow_dispatch:
         inputs:
             version:
-                description: 'Released version tag (for example: v4.6.21 or v5.0.0)'
+                # The version to build the API Reference for.
+                # Use a released tag (e.g. v5.0.9) or a plain number (e.g. 5.0.9).
+                description: 'Version (e.g. v5.0.9 or 5.0.9)'
                 required: true
                 type: string
+            use_dev_version:
+                # When checked, Composer installs from the x-dev branch instead of a released tag.
+                # Useful for building a reference before the final release is tagged.
+                # Example: version=5.0.9 + use_dev_version=true → DXP_VERSION=v5.0.x-dev, BASE_DXP_BRANCH=5.0, VIRTUAL_DXP_VERSION=5.0.9
+                description: 'Use dev version (install from x-dev branch, e.g. v5.0.x-dev)'
+                required: false
+                type: boolean
+                default: false
 
 jobs:
     open_php_api_ref_pr:
@@ -17,12 +27,30 @@ jobs:
             - name: Set version and branches
               id: version_and_branches
               run: |
+                  # Strip leading 'v' to get a plain version number (e.g. 5.0.9)
                   version="${{ inputs.version }}"
-                  base_branch="$(echo $version | sed 's/v\(.*\..*\)\..*/\1/')"
-                  work_branch="api_refs_$version"
-                  echo "version=$version" >> "$GITHUB_OUTPUT"
-                  echo "base_branch=$base_branch" >> "$GITHUB_OUTPUT"
-                  echo "work_branch=$work_branch" >> "$GITHUB_OUTPUT"
+                  version="${version#v}"
+                  base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
+                  work_branch="api_refs_v${version}"
+
+                  if [[ "${{ inputs.use_dev_version }}" == "true" ]]; then
+                    # Dev build: install from the x-dev branch and label output with the target version
+                    dxp_version="v${base_branch}.x-dev"
+                    base_dxp_branch="${base_branch}"
+                    virtual_dxp_version="${version}"
+                  else
+                    # Stable build: install from the released tag
+                    dxp_version="v${version}"
+                    base_dxp_branch=""
+                    virtual_dxp_version=""
+                  fi
+
+                  echo "version=v${version}" >> "$GITHUB_OUTPUT"
+                  echo "base_branch=${base_branch}" >> "$GITHUB_OUTPUT"
+                  echo "work_branch=${work_branch}" >> "$GITHUB_OUTPUT"
+                  echo "dxp_version=${dxp_version}" >> "$GITHUB_OUTPUT"
+                  echo "base_dxp_branch=${base_dxp_branch}" >> "$GITHUB_OUTPUT"
+                  echo "virtual_dxp_version=${virtual_dxp_version}" >> "$GITHUB_OUTPUT"
 
             - name: Checkout documentation
               uses: actions/checkout@v4
@@ -44,6 +72,9 @@ jobs:
                   SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
                   SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
                   BASE_BRANCH: ${{ steps.version_and_branches.outputs.base_branch }}
+                  DXP_VERSION: ${{ steps.version_and_branches.outputs.dxp_version }}
+                  BASE_DXP_BRANCH: ${{ steps.version_and_branches.outputs.base_dxp_branch }}
+                  VIRTUAL_DXP_VERSION: ${{ steps.version_and_branches.outputs.virtual_dxp_version }}
               run: |
                   composer config --global http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN
                   if [[ '4.6' != $BASE_BRANCH ]]; then

tools/api_refs/api_refs.sh

@@ -9,7 +9,7 @@ REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.y
 REST_API_OPENAPI_FILE_JSON=${5:-./docs/api/rest_api/rest_api_reference/openapi.json}; # Path to the REST API OpenAPI spec file
 
 DXP_EDITION='commerce'; # Edition from and for which the Reference is built
-DXP_VERSION='5.0.*'; # Version from and for which the Reference is built
+DXP_VERSION="${DXP_VERSION:-5.0.*}"; # Version from and for which the Reference is built; can be overridden by the DXP_VERSION env var (e.g. v5.0.x-dev for a dev build)
 DXP_ADD_ONS=(automated-translation rector integrated-help fieldtype-richtext-rte connector-anthropic connector-gemini shopping-list cdp connector-raptor connector-quable); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
 DXP_EDITIONS=(oss headless experience commerce); # Available editions ordered by ascending capabilities
 SF_VERSION='7.4'; # Symfony version used by Ibexa DXP
@@ -26,8 +26,8 @@ OPENAPI_FIX="$(pwd)/tools/api_refs/openapi.php"; # A script editing and fixing f
 PHP_BINARY="php -d error_reporting=`php -r 'echo E_ALL & ~E_DEPRECATED;'`"; # Avoid depreciation messages from phpDocumentor/Reflection/issues/529 when using PHP 8.2 or higher
 TMP_DXP_DIR=/tmp/ibexa-dxp-phpdoc; # Absolute path of the temporary directory in which Ibexa DXP will be installed and the PHP API Reference built
 FORCE_DXP_INSTALL=1; # If 1, empty the temporary directory, install DXP from scratch, build, remove temporary directory; if 0, potentially reuse the DXP already installed in temporary directory, keep temporary directory for future uses.
-BASE_DXP_BRANCH=''; # Branch from and for which the Reference is built when using a dev branch as version
-VIRTUAL_DXP_VERSION=''; # Version for which the reference is supposedly built when using dev branch as version
+BASE_DXP_BRANCH="${BASE_DXP_BRANCH:-}"; # Branch from and for which the Reference is built when using a dev branch as version; can be overridden by the BASE_DXP_BRANCH env var
+VIRTUAL_DXP_VERSION="${VIRTUAL_DXP_VERSION:-}"; # Version for which the reference is supposedly built when using dev branch as version; can be overridden by the VIRTUAL_DXP_VERSION env var
 
 if [ ! -d $PHP_API_OUTPUT_DIR ]; then
   echo -n "Creating ${PHP_API_OUTPUT_DIR}… ";