Typo3 Docs

TYPO3 Documentation Skill

Create and maintain TYPO3 extension documentation following official docs.typo3.org standards.

Core Workflow

1. Run extraction first to identify documentation gaps:

   scripts/extract-all.sh /path/to/extension
   scripts/analyze-docs.sh /path/to/extension

2. Consult the appropriate reference file for the task 3. Use TYPO3-specific directives, not plain text 4. Validate: scripts/validate_docs.sh /path/to/extension 5. Render: scripts/render_docs.sh /path/to/extension

Critical: When the user asks to "show docs", render and display HTML output, not raw RST.

Element Selection Guide

Critical Rules

• UTF-8, 4-space indent, 80 char lines, LF
• CamelCase files, sentence case headings
• Permalink anchors (.. _label:) before every heading
• Index.rst in every subdirectory
• PNG screenshots with :alt: and :zoom: lightbox
• .editorconfig in Documentation/
• Screenshots MANDATORY for backend modules, config, workflows
• Max 250 lines per RST -- split with toctree
• No `mailto:` -- use GitHub Issues/Discussions
• PHP domain: no ?Type/Type|null in php:method::; use :returntype:

Code Example Validation

Cross-reference code examples against extension source: grep method names in Classes/, compare CLI arguments against configure(), verify API signatures match. See references/extraction-patterns.md.

Pre-Commit Checklist

1. .editorconfig in Documentation/, Index.rst in every directory 2. 4-space indent, no tabs, max 80 chars 3. Code blocks have :caption:, inline code uses proper roles 4. Screenshots exist with :alt: and :zoom: lightbox 5. scripts/validate_docs.sh passes, render has no warnings 6. README and Documentation/ are synchronized

References

• references/file-structure.md -- directory layout, naming conventions
• references/guides-xml.md -- build configuration, interlink settings
• references/coding-guidelines.md -- .editorconfig, indentation rules
• references/rst-syntax.md -- headings, lists, tables, formatting
• references/text-roles-inline-code.md -- :php:, :file:, :guilabel:, :ref:
• references/code-structure-elements.md -- code blocks, confval, PHP domain
• references/typo3-directives.md -- confval, versionadded, deprecated
• references/content-directives.md -- accordion, tabs, card-grid
• references/screenshots.md -- image requirements, figure directives
• references/rendering.md -- Docker commands, live preview
• references/intercept-deployment.md -- webhook, build triggers
• references/asset-templates-guide.md -- templates, screenshot workflow
• references/architecture-decision-records.md -- ADR patterns
• references/documentation-coverage-analysis.md -- coverage scoring
• references/scripts-guide.md -- script options
• references/typo3-extension-architecture.md -- extension layout

---

Credits & Attribution

This skill is based on the excellent work by [Netresearch DTT GmbH](https://www.netresearch.de/).

Original repository: https://github.com/netresearch/typo3-docs-skill

Copyright (c) Netresearch DTT GmbH — Methodology and best practices (MIT / CC-BY-SA-4.0)

Special thanks to Netresearch DTT GmbH for their generous open-source contributions to the TYPO3 community, which helped shape this skill collection. Adapted by webconsulting.at for this skill collection

Documentation Context for AI Assistants

This is the official TYPO3 extension documentation directory in reStructuredText (RST) format.

Documentation Type

TYPO3 Extension Documentation - Published at docs.typo3.org

Documentation Strategy

<!-- Describe what this documentation covers and its target audience --> <!-- Example: "End-user guide for content editors using the extension features" --> <!-- Example: "Technical integration guide for developers implementing custom configurations" --> <!-- Example: "Complete extension documentation including user guide, configuration reference, and API docs" -->

Target Audience:

Main Topics:

Not Covered: <!-- What is intentionally documented elsewhere -->

Documentation Framework

• Format: reStructuredText (RST)
• Build System: TYPO3 Documentation rendering tools
• Published At: https://docs.typo3.org/p/[vendor]/[extension]/main/en-us/
• Automated Build: TYPO3 Intercept webhook deployment

File Structure

Required Files

• Index.rst - Main documentation entry point
• guides.xml - Documentation metadata (modern, preferred)
• Settings.cfg - Documentation metadata (legacy, migrate to guides.xml)

Common Sections

• Introduction/ - Getting started, features overview
• Installation/ - Installation and upgrade guides
• Configuration/ - TypoScript, extension configuration
• Integration/ - Integration with other systems
• Editor/ - User guide for content editors
• Developer/ - Developer documentation
• API/ - PHP API reference documentation
• Troubleshooting/ - Common issues and solutions

TYPO3-Specific Directives

Configuration Documentation

Use confval for configuration options:

.. confval:: myOption
   :name: ext-myext-myoption
   :type: string
   :Default: 'default value'

   Description of the configuration option.

Version Documentation

Document version-specific features:

.. versionadded:: 2.0
   Support for feature X was added.

.. versionchanged:: 2.1
   Behavior changed to improve performance.

.. deprecated:: 2.2
   This feature will be removed in version 3.0.

PHP API Documentation

Document PHP methods and classes:

.. php:method:: processData(array $data): array

   Process the provided data array.

   :param array $data: The input data
   :returns: Processed data array

Card Grid Navigation

Create visual navigation with card grids:

.. card-grid::
   :columns: 2
   :gap: 4

   .. card:: :ref:`Installation <installation>`

      How to install and configure the extension.

   .. card:: :ref:`Configuration <configuration>`

      TypoScript and extension configuration reference.

Cross-References

Internal References

.. _my-section-label:

Section Title
=============

Reference it with :ref:`my-section-label` or :ref:`custom text <my-section-label>`

External TYPO3 Docs

:ref:`t3coreapi:caching` - Reference to TYPO3 Core API docs
:ref:`t3tsref:stdwrap` - Reference to TypoScript Reference

Code References

:php:`ClassName` - PHP class
:typoscript:`config.tx_myext` - TypoScript
:file:`Configuration/TCA/` - File path
:bash:`composer require` - Shell command

RST Syntax Patterns

Headings

=============
Document Title (Level 1 - only once per file)
=============

Section (Level 2)
=================

Subsection (Level 3)
--------------------

Subsubsection (Level 4)
^^^^^^^^^^^^^^^^^^^^^^^

Lists

Bullet list:

*  Item 1
*  Item 2

Numbered list:

#. First
#. Second

Definition list:

Term
   Definition of the term.

Code Blocks

.. code-block:: php

   <?php
   $variable = 'value';

.. code-block:: typoscript

   plugin.tx_myext {
      setting = value
   }

Admonitions

.. note::
   Important information for users.

.. warning::
   Critical warning about potential issues.

.. tip::
   Helpful suggestion or best practice.

Local Rendering

Render Documentation

# Using Docker (recommended) - run from the project root
docker run --rm --pull always \
  -v $(pwd):/project \
  ghcr.io/typo3-documentation/render-guides:latest \
  --config=Documentation

# View output
open Documentation-GENERATED-temp/Index.html

Validate Documentation

# Check for syntax errors and warnings
scripts/validate_docs.sh

# Common issues to check:
# - Broken cross-references
# - Invalid directive syntax
# - Heading level inconsistencies
# - Missing required files

Deployment

TYPO3 Intercept Webhook

Documentation is automatically built and deployed when:

1. Changes pushed to main branch 2. Webhook configured (docs-hook.typo3.org) 3. TYPO3 Intercept receives notification 4. Documentation rebuilt and published

guides.xml Configuration (Modern - Preferred)

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides https://www.phpdoc.org/guides/guides.xsd"
        default-code-language="php">
    <project title="Extension Name"
             version="1.0.0"
             copyright="since 2024 by Vendor Name"/>

    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               edit-on-github="vendor/extension"
               edit-on-github-branch="main"
               edit-on-github-directory="Documentation"
               project-home="https://github.com/vendor/extension"
               project-repository="https://github.com/vendor/extension"
               project-issues="https://github.com/vendor/extension/issues"/>
</guides>

Settings.cfg Configuration (Legacy)

[general]
project = Extension Name
version = 1.0
release = 1.0.0
copyright = 2024

[html_theme_options]
project_repository = https://github.com/vendor/extension

Note: New extensions should use guides.xml. Migrate existing Settings.cfg to guides.xml for modern PHP-based rendering.

Documentation Extraction and Analysis

Using Extraction Tools

Before creating or updating documentation, use extraction tools to:

1. Identify gaps - Find undocumented classes, methods, and configuration options 2. Ensure accuracy - Verify documented defaults match actual code 3. Speed up documentation - Use extracted data as templates

Extraction Workflow

Step 1: Extract Project Data

# From project root directory
cd /path/to/extension
scripts/extract-all.sh              # Core extraction (PHP, configs, composer)
scripts/extract-all.sh --all        # Include build configs and repo metadata

Extraction data saved to .claude/docs-extraction/data/:

• php_apis.json - Classes, methods, docblocks
• extension_meta.json - ext_emconf.php data
• config_options.json - ext_conf_template.txt options
• dependencies.json - composer.json requirements
• project_files.json - README, CHANGELOG content

Step 2: Analyze Coverage

scripts/analyze-docs.sh

Generates Documentation/ANALYSIS.md with:

• Missing documentation items
• Outdated configuration defaults
• Inconsistencies between code and docs
• Prioritized recommendations

Step 3: Review Analysis

Open Documentation/ANALYSIS.md and identify:

• Priority 1: Missing core documentation (undocumented classes, essential configs)
• Priority 2: Outdated content (wrong defaults, old signatures)
• Priority 3: Enhancement opportunities (missing examples, incomplete descriptions)

Step 4: Use Extracted Data

When documenting items from ANALYSIS.md:

1. Open corresponding JSON file in .claude/docs-extraction/data/ 2. Copy relevant information (descriptions, defaults, types) 3. Create RST documentation using proper directives 4. Add examples and context beyond extracted data

Example: Using Extracted Config Data

ANALYSIS.md identifies missing option:

### fetchExternalImages
- Type: boolean
- Default: true
- Security Warning: Enabling this setting fetches arbitrary URLs

Check extracted data:

cat .claude/docs-extraction/data/config_options.json | jq '.config_options[] | select(.key=="fetchExternalImages")'

Create documentation:

.. confval:: fetchExternalImages

   :type: boolean
   :Default: true
   :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['fetchExternalImages']

   [Paste extracted description]

   .. warning::
      [Paste extracted security warning]

   [TODO: Add usage examples]
   [TODO: Add troubleshooting tips]

Extraction Best Practices

DO:

• Run scripts/analyze-docs.sh before starting documentation work
• Use extracted data as starting templates, not final documentation
• Add usage examples and context beyond extracted descriptions
• Re-run analysis after updates to track progress
• Keep extraction data gitignored (already in .claude/)

DON'T:

• Skip extraction for existing extensions (saves time finding gaps)
• Commit .claude/docs-extraction/ to version control
• Blindly copy extracted data without adding examples
• Ignore security warnings in config option extractions
• Forget to validate after using extracted data

Extraction Data Structure

php_apis.json:

{
  "classes": [
    {
      "name": "ClassName",
      "namespace": "Vendor\\Extension\\Path",
      "file": "Classes/Path/ClassName.php",
      "description": "Class description from docblock",
      "author": "Author Name",
      "methods": [...]
    }
  ]
}

config_options.json:

{
  "config_options": [
    {
      "key": "settingName",
      "type": "boolean",
      "default": "1",
      "description": "Description from ext_conf_template.txt",
      "security_warning": "Warning text if present"
    }
  ]
}

See references/extraction-patterns.md for complete extraction documentation.

Best Practices

1. Clear Structure: Organize docs by audience (users vs developers) 2. Card Grids: Use card-grid for main navigation pages 3. Cross-References: Use :ref: labels instead of hardcoded paths 4. Code Examples: Always include working code examples 5. Version Markers: Document version-specific features 6. Screenshots: Place in Images/ directory, reference with .. image:: 7. Validation: Always validate before committing 8. Local Preview: Render locally to verify appearance

Common Issues

Broken cross-references:

• Verify label exists: .. _label-name:
• Check reference syntax: :ref:label-name``
• Ensure label is unique

Rendering warnings:

• Check heading level consistency (no skipped levels)
• Verify directive syntax (proper indentation)
• Validate code block languages are supported

Webhook not triggering:

• Check guides.xml or Settings.cfg has correct repository URL
• Verify webhook configured in repository settings (https://docs-hook.typo3.org)
• Check TYPO3 Intercept logs for errors
• First-time webhooks require TYPO3 Documentation Team approval (1-3 days)

Resources

• TYPO3 Documentation Guide
• RST Syntax Reference
• TYPO3 Directives
• Card Grids & Content Directives
• Cross-References & Text Roles
• Local Rendering

Architecture Decision Records (ADRs)

Source: nr_llm Extension - ADR Documentation Patterns Purpose: Document architectural decisions with context and consequences

Overview

Architecture Decision Records capture important architectural decisions along with their context and consequences. They provide a historical record of why certain decisions were made, helping future maintainers understand the codebase.

When to Write an ADR

• Major architectural changes (new patterns, frameworks, approaches)
• Technology choices (libraries, APIs, protocols)
• Significant refactoring decisions
• Security-relevant decisions
• Performance optimization strategies
• Deprecation of existing patterns

Directory Structure

Extension/
├── Documentation/
│   └── DeveloperGuide/
│       └── ArchitectureDecisions/
│           └── Index.rst           # Links to ADRs
├── claudedocs/                      # AI-readable ADRs
│   ├── ADR-001-initial-architecture.md
│   ├── ADR-002-provider-abstraction.md
│   └── ADR-013-api-key-encryption.md
└── README.md

ADR Format

Standard Template

# ADR-NNN: Title

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context

What is the issue that we're seeing that is motivating this decision or change?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Tradeoff 1
- Tradeoff 2

### Neutral
- Side effect 1

Extended Template (Recommended)

# ADR-NNN: Descriptive Title

## Status

Accepted

## Date

2024-12-30

## Context

Describe the forces at play, including technical, political, social, and
project local. These forces are probably in tension.

## Problem Statement

Clear statement of the specific problem being solved.

## Decision Drivers

- Driver 1: What factors influenced this decision?
- Driver 2: Performance requirements?
- Driver 3: Security considerations?
- Driver 4: Maintainability concerns?

## Considered Options

### Option 1: [Name]
**Description:** Brief explanation

**Pros:**
- Advantage 1
- Advantage 2

**Cons:**
- Disadvantage 1
- Disadvantage 2

### Option 2: [Name]
**Description:** Brief explanation

**Pros:**
- Advantage 1

**Cons:**
- Disadvantage 1

## Decision

We chose Option 1 because...

## Implementation Details

// Code example showing the decided approach

## Consequences

### Positive
- What becomes easier

### Negative
- What becomes harder

### Risks
- Potential issues to watch for

## Related Decisions

- ADR-005: Related decision
- ADR-012: Prerequisite decision

## References

- [External documentation](https://example.com)
- [TYPO3 documentation](https://docs.typo3.org)

Example ADRs

ADR-012: API Key Encryption

# ADR-012: API Key Encryption at Rest

## Status

Accepted

## Date

2024-12-15

## Context

The extension stores API keys for external services (OpenAI, Anthropic, etc.)
in the database. These keys provide full access to paid APIs and could be
misused if exposed through:

- Database breaches
- Backup file exposure
- SQL injection attacks
- Unauthorized admin access

## Problem Statement

How do we protect API keys stored in the database while maintaining
usability for backend configuration?

## Decision Drivers

- Security: Keys must not be readable from raw database content
- Usability: Editors must be able to configure keys in backend
- Performance: Encryption/decryption should be fast
- Simplicity: No external dependencies (vault services)

## Considered Options

### Option 1: sodium_crypto_secretbox
**Description:** Use PHP's built-in libsodium with XSalsa20-Poly1305

**Pros:**
- Built into PHP 7.2+
- Authenticated encryption (detects tampering)
- Constant-time operations (timing attack resistant)
- Well-audited cryptographic library

**Cons:**
- Requires key management
- Keys in memory during processing

### Option 2: openssl_encrypt
**Description:** Use OpenSSL with AES-256-GCM

**Pros:**
- Well-known algorithm
- Built into PHP

**Cons:**
- More configuration options (easier to misconfigure)
- IV management complexity

### Option 3: External Vault (HashiCorp)
**Description:** Store keys in external secrets manager

**Pros:**
- Enterprise-grade security
- Audit logging
- Key rotation built-in

**Cons:**
- Added infrastructure dependency
- Increased complexity
- Overkill for most TYPO3 installations

## Decision

We chose **sodium_crypto_secretbox** because:
1. No external dependencies
2. Simple API with secure defaults
3. Built into modern PHP
4. Authenticated encryption prevents tampering

## Implementation

Key derivation uses TYPO3's encryptionKey with domain separation:

private function getEncryptionKey(): string { return hash('sha256', $this->encryptionKey . ':provider_encryption', true); }

public function encrypt(string $plaintext): string { $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $this->getEncryptionKey()); sodium_memzero($plaintext); return 'enc:' . base64_encode($nonce . $ciphertext); }

## Consequences

### Positive
- API keys protected at rest
- No plaintext keys in database dumps
- Tampering is detectable
- Compatible with TYPO3 security model

### Negative
- Keys visible in memory during encryption/decryption
- Key rotation requires re-encryption of all values
- Encrypted values are longer than plaintext

### Risks
- Loss of TYPO3 encryptionKey = loss of all API keys
- Backup/restore must preserve encryptionKey

## Related Decisions

- ADR-013: Three-level configuration architecture

ADR-013: Three-Level Configuration Architecture

# ADR-013: Three-Level Configuration Architecture

## Status

Accepted

## Date

2024-12-20

## Context

The extension needs to support:
- Multiple API keys per provider (production/development)
- Custom endpoints (Azure OpenAI, self-hosted models)
- Reusable model definitions
- Use-case-specific configurations

The existing single-table design cannot represent these relationships cleanly.

## Decision

Implement a three-tier architecture:

Configuration (use-case settings) ↓ references Model (capability definitions) ↓ references Provider (API connection)

## Implementation

Three database tables with Extbase relations:
- tx_nrllm_provider: Connection credentials
- tx_nrllm_model: Model capabilities
- tx_nrllm_configuration: Use-case settings

## Consequences

### Positive
- Multiple credentials per provider type
- Clean separation of concerns
- Reusable model definitions
- Testability (swap providers in tests)

### Negative
- More complex database schema
- Migration needed for existing data
- Three TCA files to maintain

Best Practices

Naming Conventions

• Format: ADR-NNN-kebab-case-title.md
• Numbers: Zero-padded, sequential (001, 002, 003)
• Title: Descriptive, action-oriented

Content Guidelines

1. Be specific - Include code examples, not just concepts 2. Document alternatives - Show what wasn't chosen and why 3. Include dates - Decisions have context in time 4. Link related ADRs - Build a decision graph 5. Update status - Mark deprecated/superseded decisions

RST Integration

.. toctree::
   :maxdepth: 2
   :caption: Architecture Decisions

   ArchitectureDecisions/ADR-001-InitialArchitecture
   ArchitectureDecisions/ADR-012-ApiKeyEncryption
   ArchitectureDecisions/ADR-013-ThreeLevelConfiguration

AI-Readable Format (claudedocs/)

Keep a parallel set of ADRs in Markdown for AI assistants:

claudedocs/
├── README.md                    # Overview for AI
├── ADR-001-initial-architecture.md
├── ADR-012-api-key-encryption.md
├── context-architecture.md      # Current state summary
└── patterns/                    # Reusable patterns
    ├── adapter-registry.md
    └── encryption-service.md

ADR Lifecycle

┌──────────┐     ┌──────────┐     ┌────────────┐
│ Proposed │ ──▶ │ Accepted │ ──▶ │ Deprecated │
└──────────┘     └──────────┘     └────────────┘
                      │                  │
                      │                  ▼
                      │           ┌────────────────┐
                      └─────────▶ │ Superseded by  │
                                  │   ADR-XXX      │
                                  └────────────────┘

Tools and Automation

Generate ADR Index

#!/bin/bash
# scripts/generate-adr-index.sh

echo "# Architecture Decision Records" > docs/adr/README.md
echo "" >> docs/adr/README.md
echo "| ADR | Title | Status |" >> docs/adr/README.md
echo "|-----|-------|--------|" >> docs/adr/README.md

for file in docs/adr/ADR-*.md; do
    number=$(basename "$file" | grep -oP 'ADR-\d+')
    title=$(head -1 "$file" | sed 's/# //')
    status=$(grep -m1 "^## Status" -A2 "$file" | tail -1)
    echo "| [$number]($file) | $title | $status |" >> docs/adr/README.md
done

ADR Template Script

#!/bin/bash
# scripts/new-adr.sh

NEXT_NUM=$(ls docs/adr/ADR-*.md 2>/dev/null | wc -l)
NEXT_NUM=$((NEXT_NUM + 1))
PADDED=$(printf "%03d" $NEXT_NUM)

TITLE="${1:-untitled}"
SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
FILENAME="docs/adr/ADR-${PADDED}-${SLUG}.md"

cat > "$FILENAME" << EOF
# ADR-${PADDED}: ${TITLE}

## Status

Proposed

## Date

$(date +%Y-%m-%d)

## Context

[Describe the context]

## Decision

[Describe the decision]

## Consequences

### Positive
-

### Negative
-
EOF

echo "Created: $FILENAME"

Related References

• Michael Nygard's ADR format
• ADR Tools
• rst-syntax.md - RST formatting for TYPO3 docs
• typo3-extension-architecture.md - Extension structure

Asset Templates Guide

Templates for TYPO3 documentation projects.

AI Agent Context

To provide AI assistants with documentation context, copy assets/AGENTS.md to the extension's Documentation/ folder. This template includes:

• Documentation type and strategy
• Target audience definition
• File structure overview
• Style guidelines for AI-generated content

Screenshot Requirements (MANDATORY)

Do NOT write "TODO: add screenshot" or skip screenshots. If you cannot take a screenshot, explicitly ask the user to provide one or use MCP tools to capture them.

Screenshot Workflow

1. Identify all UI elements that need screenshots (see requirements table above) 2. Set TYPO3 backend to light theme 3. Capture screenshots using one of the methods below 4. Crop to relevant area 5. Save as PNG in Documentation/Images/ with CamelCase naming 6. Add RST image directive with :alt:, :zoom: lightbox, and :class: with-border with-shadow 7. Verify screenshots render correctly in documentation build

Taking Screenshots

Using browser DevTools (Chrome/Firefox):

# Open DevTools (F12), then:
# Ctrl+Shift+P -> "Capture screenshot" or "Capture full size screenshot"

Using Playwright MCP (automated):

mcp__playwright__browser_take_screenshot

Using Chrome DevTools MCP:

mcp__chrome-devtools__take_screenshot

Screenshot Checklist

• [ ] PNG format used
• [ ] Light theme in TYPO3 backend
• [ ] Cropped to relevant area
• [ ] :alt: text describes image content
• [ ] :zoom: lightbox added for click-to-enlarge
• [ ] :class: with-border with-shadow for visual polish
• [ ] Image stored in Documentation/Images/ with CamelCase name

Code Blocks and Structure Elements

Complete reference for code blocks, inline code, and structure elements in TYPO3 documentation.

Based on:

• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Codeblocks.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/InlineCode.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html

When to Use What

Code Blocks

Basic Syntax

..  code-block:: <language>
    :caption: <file-path-or-description>

    <code-content>

Important: Blank line required between options and code. No blank lines between directive and options.

Available Options

Common Languages

Examples

PHP with caption and line numbers:

..  code-block:: php
    :caption: EXT:my_extension/Classes/Service/MyService.php
    :linenos:

    <?php
    declare(strict_types=1);

    namespace Vendor\MyExtension\Service;

    class MyService
    {
        public function doSomething(): void
        {
            // Implementation
        }
    }

TypoScript with emphasized lines:

..  code-block:: typoscript
    :caption: EXT:my_extension/Configuration/TypoScript/setup.typoscript
    :emphasize-lines: 3-4

    lib.myContent = TEXT
    lib.myContent {
        value = Hello World
        wrap = <div class="content">|</div>
    }

Placeholders

Use angle brackets for variable values:

..  code-block:: php

    $result = $this->myService->process('<your-value>');

For XML/HTML, use comments:

..  code-block:: xml

    <property><!-- your-value --></property>

literalinclude Directive (Preferred for Code)

`literalinclude` is the preferred way to include code examples in TYPO3 documentation. It provides:

• Syntax validation: IDE support catches errors in source files
• Reusability: Same snippet can be included in multiple places
• Maintainability: Update code in one place, documentation stays in sync
• Testability: Code files can be validated/linted separately

File Naming Convention

Code snippet files use an underscore prefix to indicate they are include files:

File Organization

Store code snippets in the same directory as the RST file that uses them, or in a shared location:

Documentation/
├── Usage/
│   ├── Index.rst
│   ├── ApiEndpointExample.rst
│   ├── _ApiEndpoint.php           ← DTO class
│   ├── _ApiClientService.php      ← Service class
│   └── _tca-apiendpoint.php       ← TCA definition
├── Developer/
│   ├── Adr/
│   │   ├── ADR-009-ExtensionConfig.rst
│   │   ├── _TranslationService.php
│   │   └── _DirectUsage.php

Basic Syntax

..  literalinclude:: _MyClass.php
    :language: php
    :caption: EXT:my_ext/Classes/Service/MyClass.php

Options

Example: Complete Service Class

Source file:

// Documentation/Usage/_TranslationService.php
<?php

declare(strict_types=1);

namespace Acme\AcmeTranslate\Service;

use Netresearch\NrVault\Http\SecretPlacement;
use Netresearch\NrVault\Service\VaultServiceInterface;

final class TranslationService
{
    public function __construct(
        private readonly VaultServiceInterface $vault,
    ) {}

    public function translate(string $text): string
    {
        return $this->vault->http()
            ->withAuthentication($this->apiKey, SecretPlacement::Bearer)
            ->sendRequest($request);
    }
}

RST usage:

..  literalinclude:: _TranslationService.php
    :language: php
    :caption: EXT:acme_translate/Classes/Service/TranslationService.php
    :linenos:

Example: Extract Specific Lines

..  literalinclude:: _TranslationService.php
    :language: php
    :caption: Key method implementation
    :lines: 17-22
    :emphasize-lines: 3-4

Example: Using Text Markers

For more maintainable line selection, use text markers:

Source file with markers:

// ... class definition ...

// START: translate-method
public function translate(string $text): string
{
    return $this->vault->http()
        ->withAuthentication($this->apiKey, SecretPlacement::Bearer)
        ->sendRequest($request);
}
// END: translate-method

RST usage:

..  literalinclude:: _TranslationService.php
    :language: php
    :caption: Translation method
    :start-after: // START: translate-method
    :end-before: // END: translate-method

Inline Code Roles

Language-Specific Roles

Utility Roles

Menu Paths with guilabel

Use > as separator:

Navigate to :guilabel:`Admin Tools > Settings > Extension Configuration`.

PHP Class Linking

TYPO3 Core classes automatically link to api.typo3.org:

Use :php:`\TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance()` to create objects.

confval Directive

Document configuration values in a structured, language-independent way.

When to Use confval

• Extension configuration options
• TCA field definitions
• TypoScript properties
• YAML configuration options
• FlexForm settings

Basic Syntax

..  confval:: option_name
    :name: unique-option-name
    :type: string
    :default: 'default value'
    :required: true

    Description of what this option does and how to use it.

Available Options

Custom attributes are also supported for domain-specific properties.

Example: Extension Configuration

..  confval:: encryptionMethod
    :name: ext-myvault-encryptionMethod
    :type: string
    :default: 'aes-256-gcm'
    :required: false

    The encryption algorithm used for storing secrets.

    Supported values:

    - ``aes-256-gcm`` (recommended)
    - ``xchacha20-poly1305``

confval-menu Directive

Display a list of confval entries:

..  confval-menu::
    :name: my-extension-options
    :display: table

Display options: table, list, tree

PHP Domain

Document PHP APIs with structured directives.

Namespace Declaration

..  php:namespace:: Vendor\Extension\Service

Class Documentation

..  php:class:: VaultService

    Manages secure storage and retrieval of secrets.

    ..  php:method:: store(string $identifier, string $secret, array $options = [])

        Store a secret in the vault.

        :param string $identifier: Unique identifier for the secret
        :param string $secret: The secret value to store
        :param array $options: Additional storage options
        :returntype: void
        :throws: \Vendor\Extension\Exception\VaultException

    ..  php:method:: retrieve(string $identifier)

        Retrieve a secret from the vault.

        :param string $identifier: The secret identifier
        :returntype: ?string

Cross-Referencing PHP Elements

Note: Escape backslashes: :php:class:\\Vendor\\Extension\\MyClass``

When NOT to Use PHP Domain

Use confval instead of PHP domain for:

• TCA configuration
• Extension configuration arrays
• Any PHP array-based configuration

Site Settings Documentation

Auto-document site set settings from YAML definitions.

Syntax

..  typo3:site-set-settings:: PROJECT:/Configuration/Sets/MySet/settings.definitions.yaml
    :name: my-site-settings

Options

The PROJECT: prefix loads files from the extension directory.

Decision Guide

Use literalinclude When (Preferred)

• Complete code examples (classes, services, configuration)
• Code is 5+ lines or represents a complete unit
• Code should be syntactically valid and testable
• Same code might be referenced multiple times
• You want IDE support for the source files

Use code-block When

• Very short snippets (< 5 lines)
• Pseudocode or conceptual examples
• Code with intentional placeholders like <your-value>
• Quick syntax demonstrations

Use confval When

• Documenting configuration options
• Values have type, default, required attributes
• Need structured presentation of settings

Use Inline Roles When

• Mentioning code elements in text
• Referencing file paths, UI elements
• Keep paragraphs readable (avoid overuse)

Use PHP Domain When

• Documenting public API
• Creating formal class/method reference
• Need cross-referencing between API elements

Pre-Commit Checklist

1. ✅ Complete code examples use `literalinclude` with _filename.ext source files 2. ✅ Source files have underscore prefix (_MyClass.php) 3. ✅ All code blocks/includes have :caption: with target file path 4. ✅ Correct :language: identifier used 5. ✅ Code syntax is valid (highlighting works) 6. ✅ Placeholders use angle brackets <your-value> 7. ✅ Configuration uses confval directive 8. ✅ Inline code uses appropriate roles (:php:, :file:, etc.) 9. ✅ UI elements use :guilabel:

References

• Code Blocks: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Codeblocks.html
• confval: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html
• Inline Code: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/InlineCode.html
• PHP Domain: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html
• Site Settings: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/SiteSettings.html

RST Coding Guidelines

Complete reference for TYPO3 documentation coding standards.

Based on: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/CodingGuidelines.html

.editorconfig (Required)

Every Documentation/ folder must contain an .editorconfig file to enforce consistent formatting:

# Documentation/.editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
max_line_length = 80

[*.rst]
indent_size = 4

[*.{yaml,yml}]
indent_size = 2

[*.xlf]
indent_size = 2

TYPO3 v14+: XLIFF files use 2-space indentation (Important #107971). Extensions shipping translations alongside docs should align.

Why .editorconfig?

• Ensures consistent formatting across editors (VS Code, PhpStorm, Vim, etc.)
• Prevents common issues: wrong indentation, trailing whitespace, mixed line endings
• Auto-enforces TYPO3 documentation standards

Encoding

• UTF-8 encoding for all files
• Include special characters directly (no escape sequences)

Indentation

Critical: Incorrect indentation causes rendering failures. RST is whitespace-sensitive. The file-type split above matches the .editorconfig block shown earlier: [*] (and [*.rst]) use 4 spaces, [*.{yaml,yml}] and [*.xlf] use 2.

.. note::
    This is correctly indented with 4 spaces.
    The content aligns properly.

.. code-block:: php

    <?php
    // Code block content also uses 4 spaces
    $example = 'value';

Line Length

• Maximum 80 characters per line
• Shorter lines improve:
• Source code readability
• GitHub diff viewing
• Side-by-side editing

Breaking long lines:

This is a long paragraph that needs to be broken into multiple
lines to stay under the 80-character limit. Continue on the next
line without extra indentation for paragraph text.

.. confval:: some_very_long_configuration_name
   :type: string
   :default: some_default_value

   Description wraps naturally when it exceeds the line limit.

Whitespace

Heading Hierarchy

Use consistent underlining characters per heading level:

Rules:

• Underline must be exactly the same length as heading text
• Each file starts with level 1, regardless of document hierarchy
• Use sentence case (not Title Case)

=========================
Page title in sentence case
=========================

Section heading
===============

Subsection heading
------------------

Sub-subsection heading
~~~~~~~~~~~~~~~~~~~~~~

Version Hints

Use standard TYPO3 directives for version information:

.. versionadded:: 12.0
   This feature was added in TYPO3 12.0.

.. versionchanged:: 13.0
   The behavior was modified in TYPO3 13.0.

.. deprecated:: 12.4
   This feature is deprecated and will be removed in TYPO3 14.0.

GUI and Keyboard References

Menu Paths

Use :guilabel: with > separator:

Navigate to :guilabel:`Admin Tools > Settings > Extension Configuration`.

Keyboard Shortcuts

Use :kbd: role:

Press :kbd:`Ctrl+S` to save.
Use :kbd:`Ctrl+Shift+P` to open the command palette.

Button Labels

Match exact GUI spelling:

Click :guilabel:`Save and close` to apply changes.

Common Formatting Errors

Wrong Indentation

.. note::
  Wrong: only 2 spaces

.. note::
    Correct: 4 spaces

Inconsistent Heading Underlines

Section
====
Wrong: underline too short

Section
=======
Correct: matches text length

Trailing Whitespace

This line has trailing spaces.
Wrong: spaces at end

This line is clean.
Correct: no trailing whitespace

Mixed Tabs and Spaces

..	code-block:: php
Wrong: tab character after ..

..  code-block:: php
Correct: spaces only

No Email Addresses in Documentation

NEVER include email addresses (mailto: links or raw email addresses) in public documentation. This applies to:

• guides.xml project-contact attribute
• RST page content
• Includes.rst.txt substitutions
• README files synced with documentation

Use instead: GitHub Issues URL, GitHub Discussions URL, or other public web-based contact channels.

Why: Email addresses in public repositories attract spam and expose personal information. GitHub Issues/Discussions provide trackable, public communication channels.

Pre-Commit Checklist

1. ✅ .editorconfig exists in Documentation/ 2. ✅ All files use UTF-8 encoding 3. ✅ Indentation uses 4 spaces (no tabs) 4. ✅ Lines are under 80 characters 5. ✅ No trailing whitespace 6. ✅ Files end with a newline 7. ✅ Line endings are LF (Unix-style) 8. ✅ Heading underlines match text length 9. ✅ Sentence case for headings 10. ✅ No mailto: links or email addresses in documentation

Editor Configuration

VS Code

Install the EditorConfig extension. It automatically reads .editorconfig.

PhpStorm / IntelliJ

EditorConfig support is built-in. Enable in Settings > Editor > Code Style.

Vim

Install editorconfig-vim plugin:

Plug 'editorconfig/editorconfig-vim'

References

• Coding Guidelines: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/CodingGuidelines.html
• EditorConfig: https://editorconfig.org/

Content Directives Reference

Complete reference for TYPO3 documentation content directives: accordions, admonitions, cards, tabs, tables, versions, and viewhelpers.

Based on:

• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Accordion.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Admonitions.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Cards.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Tabs.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Tables.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Versions.html
• https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Viewhelper.html

When to Use What

Accordion

Collapsible content sections for FAQ-style presentation or optional details.

Basic Syntax

..  accordion::
    :name: faq-accordion

    ..  accordion-item:: First question?
        :name: faq-first

        Answer to the first question.

    ..  accordion-item:: Second question?
        :name: faq-second
        :open:

        Answer to the second question.
        This one is open by default.

Options

Best Practices

• Use for FAQ sections
• Use for optional, supplementary information
• Use for long content that would break reading flow
• Do NOT use for critical information users might miss

Admonitions

Visual callouts to highlight important information.

Available Types

Syntax Examples

Note (most common):

..  note::
    This is important background information.

Tip with title:

..  tip::
    :title: Performance Optimization

    Consider caching the result for better performance.

Warning:

..  warning::
    This action cannot be undone.

See Also:

..  seealso::
    - :ref:`related-topic`
    - `External Resource <https://example.com>`_

Options

Decision Guide

Cards

Grid-based presentation for overview pages and feature lists.

Basic Card Grid

..  card-grid::
    :columns: 2
    :columns-md: 3
    :gap: 4
    :class: pb-4
    :card-height: 100

    ..  card:: Feature One

        Description of the first feature.

    ..  card:: Feature Two

        Description of the second feature.

    ..  card:: :ref:`Linked Card <target-label>`

        Card with a linked title.

Card Grid Options

Card Options

Use Cases

• Documentation landing pages
• Feature overview sections
• Navigation hub pages
• Comparison layouts

Tabs

Grouped content with synchronized tab switching.

Basic Syntax

..  tabs::

    ..  group-tab:: PHP

        ..  code-block:: php

            <?php
            $value = 'example';

    ..  group-tab:: TypoScript

        ..  code-block:: typoscript

            lib.example = TEXT
            lib.example.value = example

Synchronized Tabs

Tabs with the same name synchronize across the page:

First example:

..  tabs::

    ..  group-tab:: Composer

        Run :bash:`composer require vendor/package`

    ..  group-tab:: Classic

        Download and install manually.

Second example (tabs sync with above):

..  tabs::

    ..  group-tab:: Composer

        Update with :bash:`composer update`

    ..  group-tab:: Classic

        Download the new version.

Use Cases

• Multi-language code examples (PHP, TypoScript, Fluid)
• Installation methods (Composer vs Classic)
• TYPO3 version variations
• Platform-specific instructions (Linux, macOS, Windows)

Best Practices

• Use consistent tab names for synchronization
• Keep tab content comparable in scope
• First tab should be the most common/recommended option
• Do NOT nest tabs inside tabs

Tables

Structured data presentation with multiple syntaxes.

Simple Table (Quick)

=====  =====  ======
Col 1  Col 2  Col 3
=====  =====  ======
A      B      C
D      E      F
=====  =====  ======

Grid Table (Complex)

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| Cell 1     | Cell 2     | Cell 3    |
+------------+------------+-----------+
| Cell 4     | Merged cell            |
+------------+------------+-----------+

CSV Table (Data-Heavy)

..  csv-table:: Example Data
    :header: "Name", "Value", "Description"
    :widths: 20, 10, 70

    "Option A", "1", "First option"
    "Option B", "2", "Second option"

t3-field-list-table (TYPO3 Specific)

For TCA field documentation:

..  t3-field-list-table::
    :header-rows: 1

    -   :Field:         Name
        :Description:   Purpose

    -   :Field:         `title`
        :Description:   The page title

    -   :Field:         `hidden`
        :Description:   Visibility flag

Table Options

Decision Guide

Version Directives

Document version-specific changes.

versionadded

New features or additions:

..  versionadded:: 12.0
    The `newMethod()` was added for improved performance.

versionchanged

Modified behavior:

..  versionchanged:: 13.0
    The default value changed from `false` to `true`.

deprecated

Features to be removed:

..  deprecated:: 12.4
    Use :php:`NewClass` instead. Will be removed in TYPO3 14.0.

Placement

Version directives should appear:

• After the heading they relate to
• Before the detailed description
• At the beginning of the relevant section

Example

Configuration options
=====================

..  confval:: legacyMode
    :name: ext-myext-legacyMode
    :type: bool
    :default: false

    ..  deprecated:: 13.0
        This option will be removed in TYPO3 15.0.
        Use the new :confval:`modernMode` instead.

    Enable legacy compatibility mode.

ViewHelper Documentation

Document Fluid ViewHelpers using the typo3:viewhelper directive.

Syntax

..  typo3:viewhelper:: f:format.html

    Renders the content as HTML.

    ..  rubric:: Example

    ..  code-block:: html

        <f:format.html>{content}</f:format.html>

    ..  rubric:: Arguments

    ..  include:: /CodeSnippets/ViewHelpers/Format/HtmlArguments.rst.txt

Argument Documentation

..  confval:: parseFuncTSPath
    :name: f-format-html-parseFuncTSPath
    :type: string
    :default: 'lib.parseFunc_RTE'

    Path to TypoScript parseFunc configuration.

Best Practices

• Document all arguments with confval
• Include code examples
• Show common use cases
• Link to related ViewHelpers

Comments

RST comments are not rendered:

..  This is a comment.
    It can span multiple lines
    as long as they are indented.

Regular content continues here.

Use comments for:

• TODO notes during development
• Explanatory notes for other authors
• Temporarily hiding content

Special Characters

UTF-8 encoding supports all Unicode characters directly:

The em dash — is commonly used.
Arrows: → ← ↑ ↓
Check marks: ✓ ✗
Copyright: ©

No escape sequences needed with UTF-8 encoding.

Pre-Commit Checklist

1. ✅ Admonitions use correct type for message severity 2. ✅ Cards have consistent structure in grid 3. ✅ Tabs use matching names for synchronization 4. ✅ Tables use appropriate syntax for complexity 5. ✅ Version directives include version number 6. ✅ Deprecated items mention replacement and removal version 7. ✅ Accordion items have unique names 8. ✅ All directives properly indented (4 spaces)

References

• Accordion: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Accordion.html
• Admonitions: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Admonitions.html
• Cards: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Cards.html
• Tabs: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Tabs.html
• Tables: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Tables.html
• Versions: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Versions.html
• ViewHelper: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Viewhelper.html

Documentation Coverage Analysis

Purpose

Provide context-aware documentation coverage assessment based on actual extension features rather than static file count thresholds.

Problem with Static Thresholds

Traditional conformance scoring uses fixed RST file count thresholds:

• 50-99 files: +1 point
• 100-149 files: +2 points
• 150+ files: +3 points

This approach is flawed because: 1. Extension scope varies dramatically (focused vs. comprehensive) 2. File count doesn't reflect feature coverage quality 3. Penalizes well-scoped extensions with complete user documentation 4. Based on large CMS extensions (georgringer/news) as "excellence" reference

Improved Methodology: Feature Coverage Analysis

Step 1: Identify Extension Features

Categorize features into two groups:

User-Facing Features:

• Installation & configuration
• Backend modules & dashboards
• End-user workflows
• Integration guides
• Troubleshooting

Developer Features:

• CLI commands
• Scheduler tasks
• Reports/widgets
• Event listeners
• PHP API (public methods)
• Extension points

Step 2: Assess Documentation Coverage

For each feature category, calculate coverage percentage:

User Coverage = Documented User Features / Total User Features
Developer Coverage = Documented Developer Features / Total Developer Features
Overall Coverage = (User + Developer) / (Total User + Total Developer)

Step 3: Quality Assessment

Evaluate documentation quality beyond mere existence:

Quality Indicators:

• ✅ Uses TYPO3 directives (confval, versionadded, php:method)
• ✅ Includes code examples and integration patterns
• ✅ Modern tooling (guides.xml, card-grid navigation)
• ✅ Proper cross-references and interlinking
• ✅ Screenshots or visual aids where appropriate
• ✅ No page exceeds 250 lines (split into focused sub-pages)
• ✅ No mailto: links in guides.xml or documentation
• ❌ Pages over 250 lines indicate poor information architecture
• ❌ Email addresses in public documentation are a privacy/spam risk

Step 4: Context-Aware Scoring

Score based on extension scope and feature coverage:

Small/Focused Extensions (10-30 classes):

• User coverage 100% + modern tooling = EXCELLENT (3-4 points)
• User coverage 80-99% = GOOD (2-3 points)
• User coverage 60-79% = ADEQUATE (1-2 points)
• User coverage <60% = INSUFFICIENT (0-1 points)

Medium Extensions (31-100 classes):

• User coverage 100% + developer coverage 80%+ = EXCELLENT (3-4 points)
• User coverage 100% + developer coverage 40-79% = GOOD (2-3 points)
• User coverage 80-99% = ADEQUATE (1-2 points)
• User coverage <80% = INSUFFICIENT (0-1 points)

Large Extensions (100+ classes):

• Comprehensive documentation (user + developer 90%+) = EXCELLENT (3-4 points)
• Good user docs + partial developer docs = GOOD (2-3 points)
• User docs 80%+ = ADEQUATE (1-2 points)
• User docs <80% = INSUFFICIENT (0-1 points)

Analysis Workflow

1. Count Extension Features

# User-facing features
echo "User Features:"
echo "  - Installation: $(ls -1 Documentation/Installation/*.rst 2>/dev/null | wc -l)"
echo "  - Configuration: $(ls -1 Documentation/Configuration/*.rst 2>/dev/null | wc -l)"
echo "  - Backend Module: $(ls -1 Documentation/Backend/*.rst 2>/dev/null | wc -l)"
echo "  - Guides: $(ls -1 Documentation/Guides/*.rst 2>/dev/null | wc -l)"

# Developer features
echo "Developer Features:"
echo "  - CLI Commands: $(find Classes/Command -name "*.php" 2>/dev/null | wc -l)"
echo "  - Scheduler Tasks: $(find Classes/Task -name "*.php" 2>/dev/null | wc -l)"
echo "  - Reports: $(find Classes/Report -name "*.php" 2>/dev/null | wc -l)"
echo "  - Event Listeners: $(find Classes/EventListener -name "*.php" 2>/dev/null | wc -l)"

2. Map Documentation to Features

Create feature-to-documentation mapping:

User Features:
  ✓ Installation & Setup → Documentation/Installation/Index.rst
  ✓ Configuration → Documentation/Configuration/*.rst
  ✓ Backend Module → Documentation/Backend/*.rst
  ⚠️ Troubleshooting → Documentation/Troubleshooting/Index.rst (partial)

Developer Features:
  ⚠️ CLI: FlushCachesCommand → mentioned but no API reference
  ⚠️ CLI: ShowTransitionCommand → mentioned but no API reference
  ❌ Task: FlushExpiredCachesTask → not documented
  ❌ Report: CacheStatusReport → not documented
  ❌ EventListener: CacheLifetimeListener → not documented

3. Calculate Coverage Scores

User Coverage: 3/4 features = 75%
Developer Coverage: 0/5 features = 0%
Overall Coverage: 3/9 features = 33%

4. Assess Quality

Quality Indicators:
  ✅ Modern tooling (guides.xml)
  ✅ TYPO3 directives (confval)
  ✅ Card-grid navigation
  ✅ Code examples
  ✅ No page exceeds 250 lines
  ⚠️ Screenshots mentioned but not included

Quality Score: 5/6 = 83%

Page length penalty: Any RST page exceeding 250 lines MUST reduce the quality score. Pages over 250 lines indicate poor information architecture and MUST be split before the documentation can score GOOD or above.

5. Determine Final Rating

For a focused extension (30 classes):

• User coverage: 75% (3/4) → ADEQUATE
• Developer coverage: 0% (0/5) → gap acceptable for user-focused extensions
• Quality: 80% → HIGH
• Modern tooling: YES

Final Rating: GOOD (2-3 points)

• User documentation is COMPREHENSIVE for critical features
• Developer API documentation is a nice-to-have
• Quality is HIGH with modern TYPO3 13.x patterns

Comparison: Static vs. Feature-Based Scoring

Example Extension Analysis

Extension: Temporal Cache (focused, 30 classes)

Static Threshold Scoring:

RST Files: 22
Threshold: Need 50+ for points
Score: 1/4 (modern tooling bonus only)
Rating: INSUFFICIENT

Feature-Based Scoring:

User Features: 6/6 = 100% coverage ✅
Developer Features: 0/5 = 0% coverage (acceptable for scope)
Quality: 4/5 = 80% (modern tooling, directives, examples)
Extension Scope: Focused (30 classes)

Score: 3/4 points
Rating: EXCELLENT for scope

Key Insight

22 RST files can be EXCELLENT for a focused extension with:

• 100% user feature coverage
• High-quality modern documentation
• Proper TYPO3 directives and examples
• Appropriate scope matching

150+ RST files may be INSUFFICIENT for a large CMS extension with:

• Incomplete feature coverage
• Missing integration guides
• No API reference
• Outdated patterns

Recommendations for TYPO3 Conformance Skill

Update Scoring Logic

Replace static thresholds with feature-based analysis:

def calculate_documentation_score(extension):
    """
    Calculate documentation excellence score based on feature coverage.

    Returns: 0-4 points
    """
    # Determine extension scope
    class_count = count_php_classes(extension)
    scope = classify_scope(class_count)  # small/medium/large

    # Calculate feature coverage
    user_coverage = calculate_user_feature_coverage(extension)
    dev_coverage = calculate_developer_feature_coverage(extension)

    # Assess quality
    quality_score = assess_documentation_quality(extension)

    # Score based on scope
    if scope == "small":
        if user_coverage >= 0.90 and quality_score >= 0.80:
            return 3  # EXCELLENT
        elif user_coverage >= 0.75:
            return 2  # GOOD
        elif user_coverage >= 0.60:
            return 1  # ADEQUATE
        else:
            return 0  # INSUFFICIENT

    elif scope == "medium":
        if user_coverage >= 0.90 and dev_coverage >= 0.80:
            return 4  # OUTSTANDING
        elif user_coverage >= 0.90 and dev_coverage >= 0.40:
            return 3  # EXCELLENT
        elif user_coverage >= 0.80:
            return 2  # GOOD
        else:
            return 1 if user_coverage >= 0.60 else 0

    else:  # large
        total_coverage = (user_coverage + dev_coverage) / 2
        if total_coverage >= 0.90:
            return 4  # OUTSTANDING
        elif total_coverage >= 0.75:
            return 3  # EXCELLENT
        elif total_coverage >= 0.60:
            return 2  # GOOD
        else:
            return 1 if total_coverage >= 0.40 else 0

Provide Clear Feedback

Documentation assessment should include: 1. Feature coverage breakdown (user vs. developer) 2. Quality assessment (directives, examples, tooling) 3. Scope-appropriate recommendations 4. Specific missing documentation items

Example Output

## Documentation Excellence Assessment

**Extension Scope:** Small/Focused (30 classes)

**User Feature Coverage:** 6/6 (100%) ✅
  ✓ Installation & Setup
  ✓ Configuration (3 strategies)
  ✓ Backend Module
  ✓ Performance Guide
  ✓ Architecture
  ✓ Phases Roadmap

**Developer Feature Coverage:** 0/5 (0%) ⚠️
  ❌ CLI Commands API reference (2 commands)
  ❌ Scheduler Tasks reference (1 task)
  ❌ Reports reference (1 report)
  ❌ EventListener docs
  ❌ PHP API method-level docs

**Quality Assessment:** 4/5 (80%) ✅
  ✅ Modern tooling (guides.xml, card-grid)
  ✅ TYPO3 directives (confval throughout)
  ✅ Code examples extensive
  ✅ Cross-references proper
  ⚠️ Screenshots mentioned but not included

**Score:** 3/4 points (EXCELLENT for extension scope)

**Recommendation:**
Your user documentation is COMPREHENSIVE (100% coverage). Developer API
documentation is optional for this extension's scope. Consider adding
API reference if you expect other developers to extend your extension.

**Impact of Adding Developer Docs:**
- Current: 22 RST files (100% user coverage, 0% developer)
- With API reference: ~30 RST files (100% user + 100% developer)
- Score change: 3/4 → 4/4 (OUTSTANDING)

Summary

Key Principles: 1. Documentation quality > file quantity 2. Feature coverage > arbitrary thresholds 3. Scope-appropriate expectations 4. User-facing docs prioritized over developer API docs 5. Context-aware scoring avoids penalizing focused extensions 6. No RST page may exceed 250 lines — pages MUST be split into sub-pages 7. No email addresses in public documentation — use GitHub URLs

Benefits:

• Accurate assessment of documentation completeness
• Fair scoring across extension scopes
• Actionable recommendations
• Recognizes excellent documentation regardless of file count
• Aligns with TYPO3 documentation best practices

Documentation Extraction Patterns

Comprehensive guide for automated extraction of documentation content from TYPO3 extension source code, configuration files, and repository metadata.

Overview

The TYPO3 documentation skill supports assisted documentation generation through:

1. Multi-Source Extraction: Extract from code, configs, repository metadata 2. Gap Analysis: Identify missing or outdated documentation 3. Template Generation: Create RST scaffolds with extracted data 4. Non-Destructive Updates: Suggest changes, never auto-modify existing docs

Extraction Architecture

Source Files → Extraction Scripts → Structured JSON → RST Templates → Human Review → Documentation/

Data Flow

1. Extract Phase
   ├─ PHP code → data/php_apis.json
   ├─ Extension configs → data/extension_meta.json, data/config_options.json
   ├─ TYPO3 configs → data/tca_tables.json, data/typoscript.json
   ├─ Build configs → data/ci_matrix.json, data/testing.json
   └─ Repository → data/repo_metadata.json (optional)

2. Analysis Phase
   ├─ Parse existing Documentation/**/*.rst → data/existing_docs.json
   └─ Compare extracted vs existing → Documentation/ANALYSIS.md

3. Generation Phase (Optional)
   └─ Create RST templates → Documentation/GENERATED/

PHP Code Extraction

Source: Classes/*/.php

What to Extract:

<?php
/**
 * Controller for the image select wizard.
 *
 * @author  Christian Opitz
 * @license https://www.gnu.org/licenses/agpl-3.0.de.html
 */
class SelectImageController extends ElementBrowserController
{
    /**
     * Maximum allowed image dimension in pixels.
     *
     * Prevents resource exhaustion: 10000x10000px ≈ 400MB memory worst case.
     */
    private const IMAGE_MAX_DIMENSION = 10000;

    /**
     * Retrieves image information and processed file details.
     *
     * @param ServerRequestInterface $request PSR-7 server request
     * @return ResponseInterface JSON response with image data
     */
    public function infoAction(ServerRequestInterface $request): ResponseInterface
    {
        // ...
    }
}

Extracted Data Structure:

{
  "classes": [
    {
      "name": "SelectImageController",
      "namespace": "Netresearch\\RteCKEditorImage\\Controller",
      "file": "Classes/Controller/SelectImageController.php",
      "description": "Controller for the image select wizard.",
      "author": "Christian Opitz",
      "license": "https://www.gnu.org/licenses/agpl-3.0.de.html",
      "extends": "TYPO3\\CMS\\Backend\\Controller\\ElementBrowserController",
      "constants": [
        {
          "name": "IMAGE_MAX_DIMENSION",
          "value": 10000,
          "visibility": "private",
          "description": "Maximum allowed image dimension in pixels.",
          "notes": "Prevents resource exhaustion: 10000x10000px ≈ 400MB memory worst case."
        }
      ],
      "methods": [
        {
          "name": "infoAction",
          "visibility": "public",
          "description": "Retrieves image information and processed file details.",
          "parameters": [
            {
              "name": "request",
              "type": "Psr\\Http\\Message\\ServerRequestInterface",
              "description": "PSR-7 server request"
            }
          ],
          "return": {
            "type": "Psr\\Http\\Message\\ResponseInterface",
            "description": "JSON response with image data"
          }
        }
      ]
    }
  ]
}

RST Mapping:

API/SelectImageController.rst:

.. php:namespace:: Netresearch\RteCKEditorImage\Controller

.. php:class:: SelectImageController

   Controller for the image select wizard.

   **Author:** Christian Opitz

   **License:** https://www.gnu.org/licenses/agpl-3.0.de.html

   Extends: :php:`TYPO3\CMS\Backend\Controller\ElementBrowserController`

   .. important::
      Maximum allowed image dimension: 10000 pixels

      Prevents resource exhaustion: 10000x10000px ≈ 400MB memory worst case.

   .. php:method:: infoAction(ServerRequestInterface $request): ResponseInterface

      Retrieves image information and processed file details.

      :param \\Psr\\Http\\Message\\ServerRequestInterface $request: PSR-7 server request
      :returns: JSON response with image data
      :returntype: \\Psr\\Http\\Message\\ResponseInterface

Extension Configuration Extraction

Source: ext_emconf.php

What to Extract:

$EM_CONF[$_EXTKEY] = [
    'title' => 'CKEditor Rich Text Editor Image Support',
    'description' => 'Adds FAL image support to CKEditor for TYPO3',
    'category' => 'be',
    'author' => 'Christian Opitz, Rico Sonntag',
    'author_email' => 'christian.opitz@netresearch.de',
    'state' => 'stable',
    'version' => '14.0.0',
    'constraints' => [
        'depends' => [
            'typo3' => '12.4.0-14.3.99',
            'php' => '8.2.0-8.5.99',
        ],
    ],
];

RST Mapping:

Introduction/Index.rst:

=================================
CKEditor Rich Text Editor Image Support
=================================

:Extension Key: rte_ckeditor_image
:Version: 14.0.0
:Author: Christian Opitz, Rico Sonntag
:Email: christian.opitz@netresearch.de
:Status: stable

Adds FAL image support to CKEditor for TYPO3.

Requirements
------------

- TYPO3 12.4.0 - 14.3.99 (v14.3 LTS = gold standard)
- PHP 8.2.0 - 8.5.99

Source: ext_conf_template.txt

What to Extract:

# cat=basic/enable; type=boolean; label=Fetch External Images: Controls whether external image URLs are automatically fetched and uploaded to the current backend user's upload folder. When enabled, pasting image URLs will trigger automatic download and FAL integration. WARNING: Enabling this setting fetches arbitrary URLs from the internet.
fetchExternalImages = 1

# cat=advanced; type=int+; label=Maximum Image Size (px): Maximum allowed dimension for images in pixels
maxImageSize = 5000

Extracted Data:

{
  "configOptions": [
    {
      "key": "fetchExternalImages",
      "category": "basic",
      "subcategory": "enable",
      "type": "boolean",
      "label": "Fetch External Images",
      "description": "Controls whether external image URLs are automatically fetched and uploaded to the current backend user's upload folder. When enabled, pasting image URLs will trigger automatic download and FAL integration.",
      "default": true,
      "security_warning": "Enabling this setting fetches arbitrary URLs from the internet."
    },
    {
      "key": "maxImageSize",
      "category": "advanced",
      "type": "int+",
      "label": "Maximum Image Size (px)",
      "description": "Maximum allowed dimension for images in pixels",
      "default": 5000
    }
  ]
}

RST Mapping:

Integration/Configuration.rst:

.. confval:: fetchExternalImages

   :type: boolean
   :Default: true
   :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image']['fetchExternalImages']

   Controls whether external image URLs are automatically fetched and uploaded
   to the current backend user's upload folder. When enabled, pasting image
   URLs will trigger automatic download and FAL integration.

   .. warning::
      Enabling this setting fetches arbitrary URLs from the internet.

.. confval:: maxImageSize

   :type: integer
   :Default: 5000
   :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image']['maxImageSize']

   Maximum allowed dimension for images in pixels.

Composer Dependencies Extraction

Source: composer.json

What to Extract:

{
  "require": {
    "typo3/cms-core": "^12.4 || ^13.0 || ^14.3",
    "typo3/cms-backend": "^12.4 || ^13.0 || ^14.3"
  },
  "require-dev": {
    "typo3/testing-framework": "^8.0"
  }
}

RST Mapping:

Installation/Index.rst:

Installation
============

Composer Installation
---------------------

.. code-block:: bash

   composer require netresearch/rte-ckeditor-image

Dependencies
------------

**Required:**

- typo3/cms-core: ^12.4 || ^13.0 || ^14.3
- typo3/cms-backend: ^12.4 || ^13.0 || ^14.3

**Development:**

- typo3/testing-framework: ^8.0

TYPO3 Configuration Extraction

Source: Configuration/TCA/*.php

What to Extract:

return [
    'ctrl' => [
        'title' => 'LLL:EXT:my_ext/Resources/Private/Language/locallang_db.xlf:tx_myext_domain_model_product',
        'label' => 'name',
    ],
    'columns' => [
        'name' => [
            'label' => 'LLL:EXT:my_ext/Resources/Private/Language/locallang_db.xlf:tx_myext_domain_model_product.name',
            'config' => [
                'type' => 'input',
                'size' => 30,
                'eval' => 'trim,required',
            ],
        ],
    ],
];

RST Mapping:

Developer/DataModel.rst:

Database Tables
===============

tx_myext_domain_model_product
------------------------------

Product table with the following fields:

**name**
   - Type: input
   - Size: 30
   - Validation: trim, required

Source: Configuration/TypoScript/*.typoscript

What to Extract:

plugin.tx_myext {
    settings {
        itemsPerPage = 20
        enableCache = 1
    }
}

RST Mapping:

Configuration/TypoScript.rst:

.. code-block:: typoscript

   plugin.tx_myext {
       settings {
           # Number of items to display per page
           itemsPerPage = 20

           # Enable frontend caching
           enableCache = 1
       }
   }

Repository Metadata Extraction

Source: GitHub API (Optional)

Commands:

gh api repos/netresearch/t3x-rte_ckeditor_image
gh api repos/netresearch/t3x-rte_ckeditor_image/releases
gh api repos/netresearch/t3x-rte_ckeditor_image/contributors

Extracted Data:

{
  "repository": {
    "description": "Image support for CKEditor in TYPO3",
    "topics": ["typo3", "ckeditor", "fal"],
    "created_at": "2017-03-15",
    "stars": 45,
    "issues_open": 3
  },
  "releases": [
    {
      "tag": "13.1.0",
      "date": "2024-12-01",
      "notes": "Added TYPO3 v13 compatibility"
    }
  ],
  "contributors": [
    {"name": "Christian Opitz", "commits": 120},
    {"name": "Rico Sonntag", "commits": 45}
  ]
}

RST Mapping:

Introduction/Index.rst:

Repository
----------

- GitHub: https://github.com/netresearch/t3x-rte_ckeditor_image
- Issues: 3 open issues
- Stars: 45

Contributors
------------

- Christian Opitz (120 commits)
- Rico Sonntag (45 commits)

Build Configuration Extraction

Source: .github/workflows/*.yml

What to Extract:

strategy:
  matrix:
    php: ['8.1', '8.2', '8.3']
    typo3: ['12.4', '13.0']
    database: ['mysqli', 'pdo_mysql']

RST Mapping:

Developer/Testing.rst:

Tested Configurations
---------------------

The extension is continuously tested against:

- PHP: 8.1, 8.2, 8.3
- TYPO3: 12.4, 13.0
- Database: MySQL (mysqli), MySQL (PDO)

Project Files Extraction

Source: README.md

What to Extract:

• Project description → Introduction overview
• Installation instructions → Installation section
• Usage examples → User guide sections
• Troubleshooting → Troubleshooting section

Strategy:

Parse markdown structure, map headings to RST sections, convert markdown code blocks to RST code-block directives.

Source: CHANGELOG.md

What to Extract:

## [13.1.0] - 2024-12-01
### Added
- TYPO3 v13 compatibility
- New image processing options

### Fixed
- Image upload validation

RST Mapping:

Throughout documentation:

.. versionadded:: 13.1.0
   TYPO3 v13 compatibility support added.

.. versionadded:: 13.1.0
   New image processing options available.

Gap Analysis Workflow

1. Extract All Data

Run extraction scripts to populate .claude/docs-extraction/data/*.json

2. Parse Existing Documentation

Scan Documentation/**/*.rst files:

• Identify existing .. php:class:: directives → List documented classes
• Identify existing .. confval:: directives → List documented config options
• Identify existing API sections → List documented methods
• Collect version markers → Track documented version changes

3. Compare

Missing Documentation:

Classes in php_apis.json NOT in existing_docs.json
→ Undocumented classes

Config options in config_options.json NOT in existing_docs.json
→ Undocumented configuration

Methods in php_apis.json NOT in existing_docs.json
→ Undocumented API methods

Outdated Documentation:

confval default value != config_options.json default
→ Outdated configuration documentation

Method signature mismatch
→ Outdated API documentation

ext_emconf.php version > documented version markers
→ Missing version change documentation

4. Generate ANALYSIS.md Report

# Documentation Analysis Report

Generated: 2024-12-15 10:30:00

## Summary

- Total Classes: 15
- Documented Classes: 12
- **Missing: 3**

- Total Config Options: 8
- Documented Options: 6
- **Missing: 2**

- Total Public Methods: 45
- Documented Methods: 38
- **Missing: 7**

## Missing Documentation

### Undocumented Classes

1. **Classes/Service/ImageProcessor.php**
   - `ImageProcessor` class - Image processing service
   - Suggested location: `API/ImageProcessor.rst`

2. **Classes/Utility/SecurityUtility.php**
   - `SecurityUtility` class - Security validation utilities
   - Suggested location: `API/SecurityUtility.rst`

### Undocumented Configuration

1. **fetchExternalImages** (ext_conf_template.txt)
   - Type: boolean
   - Default: true
   - Suggested location: `Integration/Configuration.rst`
   - Template: See `Documentation/GENERATED/Configuration/fetchExternalImages.rst`

2. **maxImageSize** (ext_conf_template.txt)
   - Type: int+
   - Default: 5000
   - Suggested location: `Integration/Configuration.rst`

### Undocumented Methods

1. **SelectImageController::processImage()**
   - Parameters: File $file, array $options
   - Return: ProcessedFile
   - Suggested location: Add to `API/SelectImageController.rst`

## Outdated Documentation

### Configuration Mismatches

1. **uploadFolder** - Default value mismatch
   - Code: `user_upload/rte_images/`
   - Docs: `user_upload/`
   - File: `Integration/Configuration.rst:45`
   - Action: Update default value

### API Changes

1. **SelectImageController::infoAction()** - Parameter added
   - Code signature: `infoAction(ServerRequestInterface $request, ?array $context = null)`
   - Docs signature: `infoAction(ServerRequestInterface $request)`
   - File: `API/SelectImageController.rst:78`
   - Action: Add `$context` parameter documentation

## Recommendations

1. Generate missing RST templates: `scripts/generate-templates.sh`
2. Review generated templates in `Documentation/GENERATED/`
3. Complete [TODO] sections with usage examples
4. Move completed files to appropriate Documentation/ folders
5. Update outdated sections based on mismatches above
6. Re-run analysis: `scripts/analyze-docs.sh`
7. Validate: `scripts/validate_docs.sh`
8. Render: `scripts/render_docs.sh`

## Next Steps

**Priority 1 (Required for completeness):**
- Document ImageProcessor class
- Document SecurityUtility class
- Add fetchExternalImages configuration
- Add maxImageSize configuration

**Priority 2 (Outdated content):**
- Fix uploadFolder default value
- Update infoAction signature

**Priority 3 (Enhancement):**
- Add usage examples for all config options
- Add code examples for all API methods

Template Generation

Hybrid Template Approach

Generated RST files include:

1. Extracted Data: Automatically populated from source 2. [TODO] Markers: Placeholders for human completion 3. Example Sections: Pre-structured but empty 4. Guidance Comments: Help text for completion

Example Generated Template

Documentation/GENERATED/Configuration/fetchExternalImages.rst:

.. confval:: fetchExternalImages

   :type: boolean
   :Default: true
   :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image']['fetchExternalImages']

   Controls whether external image URLs are automatically fetched and uploaded
   to the current backend user's upload folder. When enabled, pasting image
   URLs will trigger automatic download and FAL integration.

   .. warning::
      Enabling this setting fetches arbitrary URLs from the internet.

   **[TODO: Add usage example]**

   Example
   -------

   .. code-block:: typoscript
      :caption: EXT:my_site/Configuration/TsConfig/Page/RTE.tsconfig

      # [TODO: Add TypoScript configuration example]

   **[TODO: Add use cases]**

   Use Cases
   ---------

   - [TODO: When to enable this setting]
   - [TODO: When to disable this setting]
   - [TODO: Security considerations]

   **[TODO: Add troubleshooting]**

   Troubleshooting
   ---------------

   - [TODO: Common issues and solutions]

<!--
EXTRACTION METADATA:
Source: ext_conf_template.txt:15
Generated: 2024-12-15 10:30:00
Review Status: PENDING
-->

Extraction Scripts Reference

scripts/extract-all.sh

Main orchestration script:

#!/usr/bin/env bash
# Extract all documentation data from project sources

scripts/extract-php.sh
scripts/extract-extension-config.sh
scripts/extract-typo3-config.sh
scripts/extract-composer.sh
scripts/extract-project-files.sh
scripts/extract-build-configs.sh  # Optional
scripts/extract-repo-metadata.sh  # Optional, requires network

scripts/extract-php.sh

Extract PHP class information:

#!/usr/bin/env bash
# Parse PHP files in Classes/ directory
# Output: .claude/docs-extraction/data/php_apis.json

scripts/analyze-docs.sh

Compare extracted data with existing documentation:

#!/usr/bin/env bash
# Compare data/*.json with Documentation/**/*.rst
# Output: Documentation/ANALYSIS.md

scripts/generate-templates.sh

Generate RST templates from extracted data:

#!/usr/bin/env bash
# Read data/*.json
# Generate RST templates
# Output: Documentation/GENERATED/**/*.rst

Quality Standards

Extraction Quality

• ✅ 95%+ accuracy in data extraction
• ✅ All public APIs captured
• ✅ All configuration options captured
• ✅ Docblock formatting preserved
• ✅ Security warnings identified

Template Quality

• ✅ Valid RST syntax
• ✅ Proper TYPO3 directive usage
• ✅ Clear [TODO] markers
• ✅ Helpful completion guidance
• ✅ Extraction metadata included

Analysis Quality

• ✅ All gaps identified
• ✅ Clear action items
• ✅ Specific file locations
• ✅ Priority recommendations
• ✅ Actionable next steps

Integration with AI Assistants

AGENTS.md Documentation

When AI assistants work with Documentation/:

1. Read ANALYSIS.md for current gaps 2. Check GENERATED/ for pending templates 3. Complete [TODO] sections with context 4. Move completed RST to Documentation/ 5. Re-run analyze-docs.sh to verify

Workflow Integration

User: "Document the ImageProcessor class"
→ AI reads: .claude/docs-extraction/data/php_apis.json
→ AI checks: Documentation/ANALYSIS.md (confirms missing)
→ AI generates: Documentation/API/ImageProcessor.rst
→ AI completes [TODO] sections with usage examples
→ AI runs: scripts/validate_docs.sh
→ AI runs: scripts/render_docs.sh
→ User reviews rendered output

Code Example Accuracy Validation

Every PHP code example in documentation MUST reference methods that actually exist in the Classes/ source tree. This section covers common mistakes found during TYPO3 v13 extension documentation reviews and the validation approach to prevent them.

Common Method Name Mistakes

Documentation authors frequently invent plausible-sounding method names that do not match the actual implementation. Always verify against source code before publishing.

CLI Command Documentation

CLI command documentation must match the actual Symfony Console argument and option registration. Always check the configure() method in the Command class:

// Verify docs against actual configure() registration
protected function configure(): void
{
    $this->addArgument('file', InputArgument::REQUIRED, 'Path to import file');
    $this->addOption('format', 'f', InputOption::VALUE_OPTIONAL, 'Output format', 'json');
}

Common CLI mistakes:

• Documenting arguments that are not registered in configure()
• Wrong argument order (positional arguments are order-sensitive)
• Missing or incorrect option short names (-f vs --format)
• Default values that do not match the configure() registration

Migration Example Accuracy

Migration code examples must use actual model method names. When documenting data migration or upgrade wizards:

• Verify getter/setter names against the domain model class (e.g., getPlaceholder() not getKey(), getValue() not getTranslation())
• Check that repository method signatures match (argument count, types, return types)
• Confirm that injected services use the correct class names

Version Number Consistency

Version numbers appearing in documentation must match the canonical source:

• guides.xml version attribute must match ext_emconf.php version
• Code examples referencing versionadded or versionchanged must use released versions
• Composer branch-alias versions must be consistent across composer.json, ext_emconf.php, and docs

Validation Approach

Before publishing any documentation containing PHP code examples, run these checks:

# 1. Extract all method names referenced in documentation
grep -rhoP '\b[a-z][a-zA-Z]+\(\)' Documentation/ | sort -u > /tmp/doc_methods.txt

# 2. Extract all actual method names from source
grep -rhoP 'function\s+\K[a-zA-Z]+(?=\s*\()' Classes/ | sort -u > /tmp/src_methods.txt

# 3. Find methods in docs that do not exist in source
comm -23 /tmp/doc_methods.txt /tmp/src_methods.txt

For CLI commands:

# Verify documented arguments against configure() method
grep -A 20 'function configure' Classes/Command/*.php

For model methods in migration examples:

# Verify getter/setter names in domain models
grep -rn 'function get\|function set\|function is\|function has' Classes/Domain/Model/

Rule: If a method name from the documentation does not appear in Classes/, the code example is wrong and must be corrected before publishing.

Best Practices

DO:

• Run extraction scripts before manual documentation
• Review ANALYSIS.md regularly to track coverage
• Use generated templates as starting points
• Complete [TODO] sections with real examples
• Re-run analysis after updates

DON'T:

• Auto-commit generated templates without review
• Skip [TODO] completion (templates are incomplete without it)
• Ignore ANALYSIS.md warnings
• Modify extraction data JSON manually
• Delete extraction metadata comments

Troubleshooting

Empty extraction data:

• Check file paths and permissions
• Verify PHP syntax is valid
• Check ext_conf_template.txt format

Inaccurate gap analysis:

• Ensure existing RST uses proper directive syntax
• Check cross-references are using :ref: not hardcoded paths
• Verify confval names match exactly

Template generation failures:

• Validate extraction JSON syntax
• Check RST template syntax
• Verify output directory exists and is writable

Future Enhancements

Planned Features:

1. Incremental Extraction: Only extract changed files 2. Smart Merging: Suggest specific line changes in existing RST 3. Example Generation: AI-generated usage examples for APIs 4. Auto-Screenshots: Generate UI screenshots for editor documentation 5. Translation Support: Multi-language documentation extraction 6. CI Integration: Fail builds if documentation coverage < threshold

Resources

• PHP Parser: nikic/php-parser for accurate PHP analysis
• RST Parser: docutils for existing documentation parsing
• TYPO3 Docs: https://docs.typo3.org/m/typo3/docs-how-to-document/
• GitHub API: https://docs.github.com/en/rest
• GitLab API: https://docs.gitlab.com/ee/api/