gh-netresearch-claude-code-marketplace-netresearch-skills-bundle/skills/typo3-docs/templates/AGENTS.md

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

Target Audience:

Main Topics:

Not Covered:

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
• Settings.cfg - Documentation metadata and configuration

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
:ts:`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)
cd Documentation
docker run --rm --pull always \
  -v $(pwd):/project \
  ghcr.io/typo3-documentation/render-guides:latest \
  --config=Documentation

# View output
open Documentation-GENERATED-temp/Result/project/0.0.0/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 in Settings.cfg
3. TYPO3 Intercept receives notification
4. Documentation rebuilt and published

Settings.cfg Configuration

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

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

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 Settings.cfg has correct repository URL
• Verify webhook configured in repository settings
• Check TYPO3 Intercept logs for errors

Resources

• TYPO3 Documentation Guide
• RST Syntax Reference
• TYPO3 Directives
• Card Grids
• Cross-References
• Local Rendering