TYPO3 Render Guides Performance Report

Performance Comparison: main vs feature/php-8.5-only

Cold Build Times (No Cache)

Resource Usage Comparison

CPU Usage >100%: Indicates parallel processing via pcntl_fork across multiple cores. 440% CPU = ~4.4 cores utilized on average.

Memory Trade-off: For extra-large docs (Changelog), feature branch uses ~56% less memory (~1.3 GB vs 3 GB) because forked workers process batches and exit, avoiding memory accumulation. For smaller docs, fork overhead increases total memory but provides significant speed improvements.

Cold vs Warm Build Performance (Feature Branch)

Warm builds benefit from Twig template caching, inventory caching, and other optimizations.

Note: Warm builds benefit from incremental caching - unchanged documents are skipped entirely. Partial builds (single file modified) show the overhead of dependency checking and minimal re-rendering. The 72-96% improvement comes from skipping unchanged documents in the render phase.

Parallel Processing Comparison (Rendertest - 98 files)

Comparison of different parallelism configurations on the small documentation set.

Key Observations

• 27-29% faster even without parallelism: The feature branch's optimizations (caching patches, PHP 8.5 improvements) provide significant speedup independent of parallel processing.
• Memory trade-off: Feature branch uses ~200 MB total (vs main's 98 MB) due to fork overhead, but gains significant speed.
• Warm caching works: Feature branch warm builds are 23-38% faster than cold; main branch shows modest improvement (8.47s warm vs 9.34s cold).
• Parallelism overhead on small docs: For small documentation sets, forcing 16 workers adds slight overhead. Auto-detection or sequential mode perform best.

Parallelism shines on large docs: The parallel processing benefits are most visible on larger documentation sets (Core API: 76% faster, Core Changelog: 95% faster) where the fork overhead is amortized across many files.

Parallel Processing Comparison (TYPO3 Core API - 957 files)

Comparison of different parallelism configurations on the large documentation set.

Key insight: Sequential mode performs best on Core API docs, suggesting the parallel fork overhead outweighs benefits for ~1000 files. All modes still achieve 71-78% improvement over main branch.

Parallel Processing Comparison (TYPO3 Core Changelog - 3667 files)

Comparison of different parallelism configurations on the extra-large documentation set.

Key insight: Sequential mode outperforms auto/16-workers on Changelog docs, achieving 21x speedup. The main branch takes 20 minutes cold / 15 minutes warm while feature branch completes in under 1 minute. Total memory usage drops from ~3 GB to ~1.3 GB.

Upstream Contributions

Performance patches submitted to phpDocumentor/guides monorepo.

Submitted Pull Requests (15 patches in 6 PRs)

Key Optimizations

• O(1) URI scheme lookup: Replaced 5600+ character regex with hash set lookup (~6x faster)
• O(1) document lookup: Direct hash map access for ProjectNode document entries
• Instance caching: Reuse parser instances instead of repeated instantiation
• Result caching: Cache expensive computations (URL resolution, slugger, Twig globals)
• DI container caching: Cache compiled Symfony container for faster startup

Not Submitted Upstream

Note: All upstream PRs target PHP 8.1+ and maintain backwards compatibility. The patches in this repository will be removed once the upstream PRs are merged and released.

Project Performance Changes

PHP 8.5 Upgrade & Modernization

• ✓
  Require PHP 8.5 only, drop support for PHP 8.1-8.4

  Enables access to latest PHP performance improvements and JIT optimizations
• ✓
  Apply Rector PHP 8.5 code modernizations

  First-class callable syntax, constructor property promotion, readonly properties
• ✓
  #[\Override] attributes

  Applied to all overriding methods for better static analysis

Parallel Processing (pcntl_fork)

• ★
  ForkingRenderer for parallel HTML rendering

  Renders documents in parallel using forked processes, major speed improvement for large docs
• ★
  ParallelParseDirectoryHandler

  Parses RST files in parallel for faster initial document loading
• ★
  ParallelCompileDocumentsHandler

  Parallel compilation infrastructure (currently using sequential for toctree compatibility)
• ★
  DocumentNavigationProvider

  Pre-computed prev/next navigation for parallel rendering

Caching Infrastructure

• ✓
  Inventory caching (53% render time improvement)

  Cache interlink inventory lookups to avoid repeated HTTP requests
• ✓
  Twig template caching

  Enable filesystem caching for compiled Twig templates
• ✓
  AST caching for parsed documents

  Cache parsed document AST to skip re-parsing on warm builds
• ✓
  OPcache CLI enabled in Docker

  Enable PHP OPcache for CLI mode in Docker builds

Incremental Rendering Infrastructure

• ✓
  IncrementalBuildCache

  Track document content hashes for change detection
• ✓
  ChangeDetector & DirtyPropagator

  Detect changed files and propagate dirty state through dependency graph
• ✓
  DependencyGraphPass & ExportsCollectorPass

  Build dependency graph during compilation for incremental builds
• ✓
  IncrementalTypeRenderer

  Skip rendering unchanged documents using cache data

Other Changes

• •
  Performance benchmark infrastructure

  Docker-based benchmark scripts for reproducible performance testing
• •
  ProfilingEventListener

  Pipeline timing measurement (enable with GUIDES_PROFILING=1)
• •
  composer-normalize pre-commit

  Added composer-normalize to pre-commit workflow
• •
  PHPUnit 12 compatibility

  Updated tests for PHPUnit 12 compatibility
• •
  Test stability fixes

  Clear AST cache before test runs to fix flaky tests

Compare Rendered Documentation

Review the rendered output from both branches to verify correctness:

Note: TYPO3 Core API rendered documentation (957 files) is not included due to size constraints. The performance benchmarks above demonstrate the improvement on this larger documentation set.

Incremental Build Performance (Feature Branch)

Incremental builds skip unchanged documents, only re-rendering files that have been modified or depend on changed exports. "Warm" = no changes (full cache hit), "Single File" = one document changed, "Cascade" = heavily-referenced document changed (triggers dependent re-renders).

Key Insight: Constant Time Incremental Builds

Notice that incremental build times are nearly identical across all project sizes: ~0.4-0.5s for 3668 files vs ~0.25s for 94 files. This demonstrates that incremental builds scale with the number of changed files, not the total project size.

Documents Re-rendered Per Scenario

• Warm (0 files): Nothing re-rendered - full cache hit, all documents skipped
• Single File (1 file): Only the modified document re-rendered (e.g., Index.rst has no dependents)
• Cascade (N files): Modified document + all dependents. E.g., EventDispatcher/Index.rst (156 refs) → 158 files re-rendered

Dependency Cascade

When a document's exports change (anchors, titles, citations), the system automatically re-renders dependent documents. This ensures cross-reference integrity across the documentation.

Benchmark Scenarios

• Cold: All caches cleared, fresh render from scratch
• Warm: No file changes, full cache hit
• Single File: Modify one document with no/few dependents (e.g., Index.rst)
• Cascade: Modify a heavily-referenced document (e.g., EventDispatcher/Index.rst with 156 dependents)

Benchmark Methodology

Parallel Processing: The feature branch uses pcntl_fork for parallel rendering, automatically detecting available CPU cores. Your results may vary depending on available cores. Use --parallel-workers=N to manually set the worker count.

Environment Variability: Benchmark times are highly dependent on hardware. The times shown above were measured on a dedicated benchmark machine. On different hardware (e.g., WSL2, VMs, or slower CPUs), absolute times may be 2-3× higher while maintaining similar relative improvements between branches.

Reproduce These Benchmarks

Follow these steps to reproduce the benchmark results on your own machine:

# Clone the repository
git clone https://github.com/CybotTM/render-guides.git
cd render-guides
git checkout feature/php-8.5-only

# Download test documentation
./benchmark/download-test-docs.sh TYPO3CMS-Reference-CoreApi  # Large (957 files)
./benchmark/download-test-docs.sh TYPO3-Core-Changelog        # Extra-large (3666 files)

# === Feature Branch Benchmarks ===
# Run cold benchmark on small docs (rendertest)
./benchmark/benchmark-docker.sh cold 3 small

# Run cold benchmark on large docs (TYPO3 Core API)
./benchmark/benchmark-docker.sh cold 3 large

# Run cold benchmark on extra-large docs (TYPO3 Core Changelog)
./benchmark/benchmark-docker.sh cold 3 changelog

# Run warm benchmark (Twig caches populated)
./benchmark/benchmark-docker.sh warm 3 small
./benchmark/benchmark-docker.sh warm 3 large
./benchmark/benchmark-docker.sh warm 3 changelog

# Run partial/incremental benchmark (modifies Index.rst)
./benchmark/benchmark-docker.sh partial 3 small
./benchmark/benchmark-docker.sh partial 3 large
./benchmark/benchmark-docker.sh partial 3 changelog

# === Main Branch Benchmarks (using official container) ===
# For main branch comparison, use the official TYPO3 render-guides container:
docker pull ghcr.io/typo3-documentation/render-guides:latest

# Small docs (rendertest)
docker run --rm -v $(pwd)/Documentation-rendertest:/project/Documentation \
  -v /tmp/main-output:/project/Documentation-GENERATED-temp \
  ghcr.io/typo3-documentation/render-guides:latest --no-progress

# Large docs (TYPO3 Core API)
docker run --rm -v $(pwd)/benchmark/test-docs/TYPO3CMS-Reference-CoreApi/Documentation:/project/Documentation \
  -v /tmp/main-output-large:/project/Documentation-GENERATED-temp \
  ghcr.io/typo3-documentation/render-guides:latest --no-progress

# Extra-large docs (TYPO3 Core Changelog) - warning: ~17 minutes on main branch
docker run --rm -v $(pwd)/benchmark/test-docs/TYPO3-Core-Changelog/typo3/sysext/core/Documentation:/project/Documentation \
  -v /tmp/main-output-changelog:/project/Documentation-GENERATED-temp \
  ghcr.io/typo3-documentation/render-guides:latest --no-progress

Result files: Benchmark results are saved as JSON files in benchmark/results/ with naming convention: {branch}_{scenario}_{docs}_{timestamp}.json

References

• PR #1143 — Original performance optimization proposal and discussion
• Feature Branch — Source code for this implementation
• Upstream PRs — Performance patches submitted to phpDocumentor/guides