Selfreview

mnocon · mnocon · commit ec3e49659814 · 2026-07-22T13:59:13.000+02:00
diff --git a/.agents/skills/external/ibexa-documentation/SKILL.md b/.agents/skills/external/ibexa-documentation/SKILL.md
@@ -16,8 +16,7 @@ It contains two documentation sets:
 
 Use the documentation for what the code cannot tell you:
 
-- Concepts and the content model: content types, fields, locations,
-  versions, languages, and how they relate.
+- Concepts and the content model: content types, fields, locations, versions, languages, and how they relate.
 - Release notes and changes between versions: `developer/release_notes/`.
 - Update and migration instructions: `developer/update_and_migration/`.
 - Project and feature setup, configuration, and best practices: `developer/infrastructure_and_maintenance/`.
diff --git a/.github/workflows/release_composer_package.yaml b/.github/workflows/release_composer_package.yaml
@@ -4,26 +4,53 @@ on:
     schedule:
         # Daily at 03:17 UTC. Fans out to every maintained version branch (see determine-branches).
         - cron: "17 3 * * *"
-    workflow_dispatch: ~
+    workflow_dispatch:
+        inputs:
+            version:
+                description: "Version branch to release"
+                required: true
+                default: "5.0"
+                type: string
+            devdoc_branch:
+                description: "Developer documentation branch to check out (defaults to version)"
+                required: false
+                default: ""
+                type: string
+            userdoc_branch:
+                description: "User documentation branch to check out (defaults to version)"
+                required: false
+                default: ""
+                type: string
 
 jobs:
     determine-branches:
         runs-on: ubuntu-latest
         outputs:
             branches: ${{ steps.set.outputs.branches }}
+            devdoc_branch: ${{ steps.set.outputs.devdoc_branch }}
+            userdoc_branch: ${{ steps.set.outputs.userdoc_branch }}
         steps:
             - id: set
               run: |
                   if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-                      # Manual runs only release the branch the workflow was dispatched from.
-                      branches='["${{ github.ref_name }}"]'
+                      # Manual runs release the branch chosen via the "version" input,
+                      # not necessarily the branch the workflow was dispatched from.
+                      branches='["${{ github.event.inputs.version }}"]'
+                      # Left empty when not overridden; the release job then falls back
+                      # to the version branch (matrix.branch) for the checkout ref.
+                      devdoc_branch="${{ github.event.inputs.devdoc_branch }}"
+                      userdoc_branch="${{ github.event.inputs.userdoc_branch }}"
                   else
                       # Scheduled runs always execute in the default branch's context, so they must
                       # explicitly check out each maintained version branch instead of relying on
                       # GITHUB_REF. Extend this list as new branches become active / drop EOL ones.
                       branches='["5.0"]'
+                      devdoc_branch=""
+                      userdoc_branch=""
                   fi
                   echo "branches=${branches}" >> "$GITHUB_OUTPUT"
+                  echo "devdoc_branch=${devdoc_branch}" >> "$GITHUB_OUTPUT"
+                  echo "userdoc_branch=${userdoc_branch}" >> "$GITHUB_OUTPUT"
 
     release:
         needs: determine-branches
@@ -43,13 +70,13 @@ jobs:
             # pulling the full history + every daily tag snapshot (which took minutes).
             - uses: actions/checkout@v4
               with:
-                  ref: ${{ matrix.branch }}
+                  ref: ${{ needs.determine-branches.outputs.devdoc_branch || matrix.branch }}
 
             - name: Check out user documentation
               uses: actions/checkout@v4
               with:
                   repository: ibexa/documentation-user
-                  ref: ${{ matrix.branch }}
+                  ref: ${{ needs.determine-branches.outputs.userdoc_branch || matrix.branch }}
                   path: user-docs
 
             - name: Set up Python
@@ -72,13 +99,13 @@ jobs:
                   php-version: "8.3"
                   coverage: none
 
-            # - name: Generate token
-            #   id: generate_token
-            #   uses: actions/create-github-app-token@v2
-            #   with:
-            #       app-id: ${{ secrets.AUTOMATION_CLIENT_ID }}
-            #       private-key: ${{ secrets.AUTOMATION_CLIENT_SECRET }}
-            #       owner: ${{ github.repository_owner }}
+            - name: Generate token
+              id: generate_token
+              uses: actions/create-github-app-token@v2
+              with:
+                  app-id: ${{ secrets.AUTOMATION_CLIENT_ID }}
+                  private-key: ${{ secrets.AUTOMATION_CLIENT_SECRET }}
+                  owner: ${{ github.repository_owner }}
 
             - name: Add composer keys for private packagist
               run: |
@@ -87,7 +114,7 @@ jobs:
               env:
                   SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
                   SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
-                  GITHUB_TOKEN: ${{ secrets.MY_GITHUB_TOKEN }} #${{ steps.generate_token.outputs.token }}
+                  GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
 
             # Needed to resolve the PHP API classes referenced by the docs to
             # their vendor/ source paths (dump_class_paths.php).
@@ -117,6 +144,10 @@ jobs:
             - name: Copy package README
               run: cp tools/llm_package/README.package.md README.md
 
+            - name: Smoke-test package output
+              run: |
+                  composer validate
+
             - name: Find the last tag for this branch
               id: last_tag
               env:
diff --git a/build_package_docs.py b/build_package_docs.py
@@ -1,40 +1,32 @@
 """
 Build the Composer-package Markdown docs from the MkDocs build outputs.
 
-The package bundles two documentation sets, each produced by its own MkDocs
-build with the llmstxt plugin:
-
-- ``developer/`` — ibexa/documentation-developer (this repository, built into
-  ``site/``)
-- ``user/`` — ibexa/documentation-user (checked out and built next to it, into
-  ``user-docs/site/``)
-
-Each set gets its own ``llms.txt`` table of contents at its root. The website
-outputs keep absolute https://doc.ibexa.co URLs; the Composer package must work
-offline inside vendor/ibexa/documentation-developer, so links are rewritten:
-
-- Page links (``https://doc.ibexa.co/en/latest/<path>/[#anchor]`` for the
-  developer docs, ``https://doc.ibexa.co/projects/userguide/en/latest/…`` for
-  the user docs) become relative links to the corresponding
-  ``<set>/<path>/index.md`` file — including cross-set links between the two
-  documentations. URLs matching a mkdocs-redirects entry are resolved through
-  the redirect first. URLs with no local page (other doc.ibexa.co projects,
-  images, the separately hosted API reference HTML) are left untouched.
-- PHP API class links (``…/php_api_reference/classes/<Slug>.html``) become
-  relative links to the class source file in the *installed project's*
-  vendor/ directory, using the FQCN→path map produced by
-  ``tools/llm_package/dump_class_paths.php``. The link text is upgraded to the
-  backticked FQCN (when it was just the short class name) so the class stays
-  greppable even if the target package isn't installed in the user's project.
-  Unmapped classes keep their absolute URL.
-
-Run after both ``mkdocs build``s:
-
-    php tools/llm_package/dump_class_paths.php site user-docs/site class_paths.json
-    python build_package_docs.py --version 5.0
-
-Like llmstxt_preprocess.py, all transformations are pure functions so they can
-be unit-tested (tests/python/test_build_package_docs.py).
+The package bundles two documentation sets, each produced by its own MkDocs build with the llmstxt plugin:
+
+- `developer/` — ibexa/documentation-developer
+- `user/` — ibexa/documentation-user
+
+Each set gets its own `llms.txt` table of contents at its root.
+
+The following transformations are applied to the MkDocs build outputs before writing them into the package::
+
+- Page links to developer and user documentation become relative links to the corresponding `<set>/<path>/index.md`` files, including cross-set links between the two documentations:
+
+    URLs matching a mkdocs-redirects entry are resolved through the redirect first. 
+    URLs with no local page (other doc.ibexa.co projects, images, the separately hosted API reference HTML) are left untouched.
+    Links to versions other than the current branch's version (e.g. en/4.0/…) are also left untouched.
+    
+- PHP API class links (`.../php_api_reference/classes/<Slug>.html`) become relative links to the class source file in the vendor/ director:
+
+    By using the FQCN -> path map produced by `tools/llm_package/dump_class_paths.php`.
+    The link text is upgraded to the FQCN so the class stays greppable even if the target package isn't installed in the user's project.
+
+Run after both documentation sites are built with MkDocs:
+
+``` bash
+php tools/llm_package/dump_class_paths.php site user-docs/site class_paths.json
+python build_package_docs.py --version 5.0
+```
 """
 
 import argparse
@@ -341,7 +333,7 @@ def main():
     parser.add_argument("--user-plugins", default="user-docs/plugins.yml",
                         help="User docs plugins.yml with redirect_maps")
     parser.add_argument("--class-map", default="class_paths.json",
-                        help="FQCN→vendor path map from dump_class_paths.php")
+                        help="FQCN -> vendor path map from dump_class_paths.php")
     parser.add_argument("--version", default=None,
                         help="This branch's documentation version (e.g. 5.0): links pinned to "
                              "it (en/5.0/…) are rewritten like en/latest ones")
diff --git a/tools/llm_package/README.package.md b/tools/llm_package/README.package.md
@@ -1,67 +1,31 @@
 # Ibexa DXP documentation
 
-This package contains the official Ibexa DXP documentation as plain Markdown
-files, generated from the same sources as the website. Install it into an Ibexa
-DXP project so that AI coding assistants (and humans) can read the
-documentation offline, right next to the code it describes:
+Official Ibexa DXP documentation as plain Markdown files.
 
-```bash
-composer require --dev ibexa/documentation-developer:~5.0
-```
+## Installation
 
-## Layout
+Run the following command:
 
-- `developer/` — the [developer documentation](https://doc.ibexa.co/en/latest/):
-  APIs, extension points, configuration, tutorials.
-- `user/` — the [user documentation](https://doc.ibexa.co/projects/userguide/en/latest/):
-  working with the back office, content management, commerce.
-- Each set has its own `llms.txt` at its root (`developer/llms.txt`,
-  `user/llms.txt`) — a table of contents with relative links. Start there to
-  find the right page.
-- One Markdown file per page, mirroring the URL structure of the website:
-  `developer/<section>/.../<page>/index.md` corresponds to
-  `https://doc.ibexa.co/en/latest/<section>/.../<page>/`, and
-  `user/<section>/.../<page>/index.md` to
-  `https://doc.ibexa.co/projects/userguide/en/latest/<section>/.../<page>/`.
-- `.agents/skills/external/` — agent skills for working with Ibexa DXP. When
-  the package is installed with Symfony Flex, its recipe copies them into your
-  project's `.agents/skills/ibexa/` directory.
+```bash
+composer require --dev ibexa/documentation-developer:~5.0 --no-scripts
+```
 
-## Conventions
+## Content
 
-- Links between documentation pages are relative Markdown links and work
-  offline — including cross-links between the developer and user documentation.
-- PHP API references are links to the class source in your project's `vendor/`
-  directory, with the fully qualified class name as the link text, for example
-  ``[`Ibexa\Contracts\Core\Repository\SearchService`](../../../../core/src/contracts/Repository/SearchService.php)``.
-  If your project doesn't include the package a class belongs to, the link
-  target won't exist — the class name in the link text still tells you what the
-  reference is.
-- A few links have no local equivalent and stay absolute: images, the
-  [PHP API reference](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/)
-  itself, and other documentation sites (e.g. Ibexa Connect).
+This package contains two documentation sets:
 
-## Using with AI agents
+- `developer` contains content of the [developer documentation](https://doc.ibexa.co/en/latest/).
+- `user` contains content of the [user documentation](https://doc.ibexa.co/en/latest/).
 
-Point your agent at this package, for example by adding to your project's
-`CLAUDE.md` / `AGENTS.md`:
+Each set has its own `llms.txt` at its root (`developer/llms.txt`, `user/llms.txt`) with a table of contents with relative links.
 
-```markdown
-Ibexa DXP documentation is installed locally in
-vendor/ibexa/documentation-developer/: developer documentation in developer/,
-user documentation in user/. To find a topic, read the set's table of contents
-(developer/llms.txt or user/llms.txt) or search the Markdown files, then follow
-the relative links. PHP API links in the docs point at the class sources in
-vendor/.
-```
+## Use with AI Agents
 
-## Versioning
+To use the documentation with AI agents, you can:
 
-A new tag is published whenever the generated documentation content changes;
-tag names combine the documentation branch and the build date. Use a `~5.0`
-constraint to stay on the documentation matching your Ibexa DXP version.
+- use the `ibexa-documentation` Agent skill provided by this package (recommended)
+- instruct the agent manually, by mentioning in the prompt:
 
-The documentation sources live on the version branches of
-[ibexa/documentation-developer](https://github.com/ibexa/documentation-developer)
-and [ibexa/documentation-user](https://github.com/ibexa/documentation-user)
-— contributions are welcome there.
+``` text
+Ibexa DXP documentation is installed locally in vendor/ibexa/documentation-developer/
+```
