zhongwei/gh-netresearch-claude-code-marketplace-netresearch-skills-bundle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:43:13 +08:00
commit f6d4a68978
178 changed files with 51030 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
skills/typo3-docs/.gitignore vendored Normal file
View File

@@ -0,0 +1,25 @@
# IDE
.vscode/
.idea/
# OS
.DS_Store
Thumbs.db
# Temporary files
*.tmp
*.bak
*~
# Python
__pycache__/
*.py[cod]
*.so
# Testing
.pytest_cache/
# Distribution
*.zip
dist/
build/

124
skills/typo3-docs/LICENSE Normal file
View File

@@ -0,0 +1,124 @@
TYPO3 Documentation Skill for Claude Code
Copyright (C) 2025 Netresearch DTT GmbH
This skill is licensed under the GNU General Public License version 2 or later.
────────────────────────────────────────────────────────────────────────────────
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does. Copyright (C) yyyy name of author
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker.
signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice

335
skills/typo3-docs/README.md Normal file
View File

@@ -0,0 +1,335 @@
# TYPO3 Documentation Skill
A comprehensive Claude Code skill for creating and maintaining TYPO3 extension documentation following official TYPO3 documentation standards.
## Overview
This skill provides guidance for working with TYPO3 extension documentation in reStructuredText (RST) format, including TYPO3-specific directives, local rendering with Docker, validation procedures, and automated deployment through TYPO3 Intercept.
## Features
- **Documentation Extraction** - Automated extraction from code, configs, and repository metadata
- **Gap Analysis** - Identify missing and outdated documentation
- **RST Syntax Reference** - Complete reStructuredText formatting guide
- **TYPO3-Specific Directives** - confval, versionadded, php:method, card-grid
- **Local Rendering** - Docker-based documentation rendering scripts
- **Validation Tools** - RST syntax and quality check scripts
- **Quality Standards** - Pre-commit checklists and best practices
- **TYPO3 Intercept** - Automated deployment guidance
- **AI Assistant Context** - AGENTS.md templates for Documentation/ folders
## Installation
### Download the Skill
Download the latest release from the [releases page](https://github.com/netresearch/typo3-docs-skill/releases) or install directly:
```bash
# Using curl
curl -L https://github.com/netresearch/typo3-docs-skill/archive/refs/heads/main.zip -o typo3-docs.zip
unzip typo3-docs.zip -d ~/.claude/skills/
mv ~/.claude/skills/typo3-docs-skill-main ~/.claude/skills/typo3-docs
# Or using git
git clone https://github.com/netresearch/typo3-docs-skill.git ~/.claude/skills/typo3-docs
```
### Verify Installation
The skill will automatically activate when working with TYPO3 documentation:
- Creating/updating `Documentation/*.rst` files
- Using TYPO3-specific directives
- Rendering documentation locally
- Following TYPO3 documentation guidelines
## Contents
### SKILL.md
Main skill file with comprehensive instructions for:
- Documentation structure and workflow
- Configuration documentation with confval
- Version documentation with versionadded/versionchanged
- PHP API documentation with php:method
- Card grid navigation with stretched links
- Cross-references and quality standards
### references/
**rst-syntax.md** - Complete RST syntax reference:
- Headings, code blocks, lists, links
- Tables, admonitions, images
- Whitespace rules and common mistakes
**typo3-directives.md** - TYPO3-specific directives:
- confval for configuration values
- Version directives (added/changed/deprecated)
- PHP domain (class/method/property)
- Card grids with stretched links
- Intersphinx references
- Quality checklists
**extraction-patterns.md** - Documentation extraction guide:
- Multi-source extraction patterns (PHP, configs, repository)
- Data-to-RST mapping strategies
- Gap analysis workflow
- Template generation approaches
- Quality standards for extraction
**typo3-extension-architecture.md** - TYPO3 official file structure reference:
- File structure hierarchy with priority weights
- Directory structure weights (Classes/, Configuration/, Resources/)
- Extraction weight matrix (Priority 1-5)
- Quality weighting algorithm
- Gap analysis priority calculation
- Documentation mapping strategies
### templates/
**AGENTS.md** - AI assistant context template:
- Documentation strategy and audience
- TYPO3 RST syntax patterns
- Directive usage examples
- Cross-reference patterns
- Validation and rendering procedures
### scripts/
**add-agents-md.sh** - Add AI context to Documentation/:
- Creates AGENTS.md from template
- Provides documentation context for AI assistants
- Helps AI understand project documentation structure
**validate_docs.sh** - Validation script:
- Checks RST syntax
- Validates Settings.cfg and Index.rst
- Detects encoding issues
- Identifies trailing whitespace
**render_docs.sh** - Rendering script:
- Renders documentation locally with Docker
- Uses official TYPO3 render-guides image
- Outputs to Documentation-GENERATED-temp/
**extract-all.sh** - Documentation extraction orchestrator:
- Extracts data from PHP code, extension configs, composer.json
- Optional: build configs (.github/workflows, phpunit.xml)
- Optional: repository metadata (GitHub/GitLab API)
- Outputs to .claude/docs-extraction/data/*.json
**analyze-docs.sh** - Documentation coverage analysis:
- Compares extracted data with existing Documentation/
- Identifies missing and outdated documentation
- Generates Documentation/ANALYSIS.md with recommendations
- Prioritizes action items for systematic documentation
**extract-php.sh** - PHP code extraction:
- Parses Classes/**/*.php for docblocks and signatures
- Extracts class descriptions, methods, constants
- Outputs to .claude/docs-extraction/data/php_apis.json
**extract-extension-config.sh** - Extension configuration extraction:
- Parses ext_emconf.php for extension metadata
- Parses ext_conf_template.txt for configuration options
- Identifies security warnings in config comments
- Outputs to extension_meta.json and config_options.json
**extract-composer.sh** - Composer dependency extraction:
- Extracts requirements and dev-requirements
- Outputs to .claude/docs-extraction/data/dependencies.json
**extract-project-files.sh** - Project file extraction:
- Extracts content from README.md, CHANGELOG.md
- Outputs to .claude/docs-extraction/data/project_files.json
**extract-build-configs.sh** - Build configuration extraction (optional):
- Extracts CI/CD configurations, PHPUnit settings
- Outputs to .claude/docs-extraction/data/build_configs.json
**extract-repo-metadata.sh** - Repository metadata extraction (optional):
- Fetches GitHub/GitLab repository information
- Requires gh or glab CLI tools
- Outputs to .claude/docs-extraction/data/repo_metadata.json
- Cached for 24 hours
## Usage
The skill automatically activates for TYPO3 documentation tasks. You can also manually invoke it:
```
/skill typo3-docs
```
### Quick Examples
**Add AI Assistant Context:**
```bash
cd /path/to/your-extension
~/.claude/skills/typo3-docs/scripts/add-agents-md.sh
# Creates Documentation/AGENTS.md with TYPO3 documentation patterns
```
**Extract and Analyze Documentation:**
```bash
cd /path/to/your-extension
# Extract data from code and configs
~/.claude/skills/typo3-docs/scripts/extract-all.sh
# Analyze documentation coverage
~/.claude/skills/typo3-docs/scripts/analyze-docs.sh
# Review the analysis report
cat Documentation/ANALYSIS.md
# Extract with optional sources
~/.claude/skills/typo3-docs/scripts/extract-all.sh --all # Include build configs & repo metadata
```
**Document Configuration:**
```rst
.. confval:: fetchExternalImages
:type: boolean
:Default: true
:Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['setting']
Controls whether external image URLs are automatically fetched.
```
**Document Version Changes:**
```rst
.. versionadded:: 13.0.0
The CKEditor plugin now requires ``StyleUtils`` and ``GeneralHtmlSupport``
dependencies for style functionality.
```
**Create Card Grid Navigation:**
```rst
.. card-grid::
:columns: 1
:columns-md: 2
.. card:: 📘 Introduction
Extension overview and features
.. card-footer:: :ref:`Read more <introduction>`
:button-style: btn btn-primary stretched-link
```
**Validate Documentation:**
```bash
~/.claude/skills/typo3-docs/scripts/validate_docs.sh /path/to/project
```
**Render Documentation:**
```bash
~/.claude/skills/typo3-docs/scripts/render_docs.sh /path/to/project
```
## Deployment Setup
**Enable automatic documentation publishing to docs.typo3.org:**
### Prerequisites
1. Extension published in [TYPO3 Extension Repository (TER)](https://extensions.typo3.org/)
2. Git repository URL referenced on TER detail page
3. Valid Documentation/ structure with Index.rst and Settings.cfg
### Quick Webhook Setup
**GitHub:**
```
Settings → Webhooks → Add webhook
Payload URL: https://docs-hook.typo3.org
Content type: application/json
SSL: Enabled
Events: Just the push event
Active: ✓
```
**GitLab:**
```
Settings → Webhooks
URL: https://docs-hook.typo3.org
Triggers: Push events + Tag push events
SSL: Enabled
```
### Verification
After first push, check:
- **Webhook delivery**: GitHub/GitLab webhook recent deliveries (expect `200`)
- **Build status**: [Intercept Dashboard](https://intercept.typo3.com/admin/docs/deployments)
- **Published docs**: `https://docs.typo3.org/p/{vendor}/{extension}/main/en-us/`
**First build requires approval** by TYPO3 Documentation Team (1-3 business days). Future builds are automatic.
**Full webhook setup guide:** [references/intercept-deployment.md](references/intercept-deployment.md)
## Quality Standards
Before committing documentation changes, ensure:
- ✅ No rendering warnings
- ✅ No broken cross-references
- ✅ All confval directives complete
- ✅ Version information for new features
- ✅ Card grids use stretched-link
- ✅ UTF-8 emoji icons in card titles
- ✅ Code blocks specify language
- ✅ Proper heading hierarchy
- ✅ No trailing whitespace
## Resources
**Official Documentation:**
- [TYPO3 Documentation Guide](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/)
- [RST Reference](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
- [Rendering with Docker](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/RenderingDocs/Index.html)
**Example Projects:**
- [TYPO3 Best Practice Extension](https://github.com/TYPO3BestPractices/tea)
- [RTE CKEditor Image](https://docs.typo3.org/p/netresearch/rte-ckeditor-image/main/en-us/)
**TYPO3 Intercept:**
- [Deployment Dashboard](https://intercept.typo3.com/admin/docs/deployments)
## Contributing
Contributions are welcome! Please follow these guidelines:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/improvement`)
3. Make your changes
4. Test the skill thoroughly
5. Commit your changes (`git commit -m 'Add improvement'`)
6. Push to the branch (`git push origin feature/improvement`)
7. Create a Pull Request
## License
This skill is licensed under the same license as the [TYPO3 RTE CKEditor Image extension](https://github.com/netresearch/t3x-rte_ckeditor_image) - GPL-2.0-or-later.
## Support
**Issues and Questions:**
- GitHub Issues: [Report issues](https://github.com/netresearch/typo3-docs-skill/issues)
- TYPO3 Slack: [#typo3-cms](https://typo3.slack.com/archives/typo3-cms)
## Credits
Created by Netresearch DTT GmbH for the TYPO3 community.
Based on:
- [TYPO3 Official Documentation Standards](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/)
- [Anthropic Skill Creator](https://github.com/anthropics/skills/tree/main/skill-creator)
- Real-world usage in [RTE CKEditor Image Extension](https://github.com/netresearch/t3x-rte_ckeditor_image)
---
**Version:** 1.0.0
**Maintained By:** Netresearch DTT GmbH
**Last Updated:** 2025-10-18

1123
skills/typo3-docs/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

317
skills/typo3-docs/references/documentation-coverage-analysis.md Normal file
View File

@@ -0,0 +1,317 @@
# 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
### 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
```bash
# 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
⚠️ Screenshots mentioned but not included
Quality Score: 4/5 = 80%
```
### 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:
```python
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
**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

867
skills/typo3-docs/references/extraction-patterns.md Normal file
View File

@@ -0,0 +1,867 @@
# 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
<?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:**
```json
{
"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:**
```rst
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:**
```php
$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' => '13.1.0',
'constraints' => [
'depends' => [
'typo3' => '12.4.0-13.5.99',
'php' => '8.1.0-8.3.99',
],
],
];
```
**RST Mapping:**
```rst
Introduction/Index.rst:
=================================
CKEditor Rich Text Editor Image Support
=================================
:Extension Key: rte_ckeditor_image
:Version: 13.1.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 - 13.5.99
- PHP 8.1.0 - 8.3.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:**
```json
{
"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:**
```rst
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:**
```json
{
"require": {
"typo3/cms-core": "^12.4 || ^13.0",
"typo3/cms-backend": "^12.4 || ^13.0"
},
"require-dev": {
"typo3/testing-framework": "^8.0"
}
}
```
**RST Mapping:**
```rst
Installation/Index.rst:
Installation
============
Composer Installation
---------------------
.. code-block:: bash
composer require netresearch/rte-ckeditor-image
Dependencies
------------
**Required:**
- typo3/cms-core: ^12.4 || ^13.0
- typo3/cms-backend: ^12.4 || ^13.0
**Development:**
- typo3/testing-framework: ^8.0
```
## TYPO3 Configuration Extraction
### Source: Configuration/TCA/*.php
**What to Extract:**
```php
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:**
```rst
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:**
```typoscript
plugin.tx_myext {
settings {
itemsPerPage = 20
enableCache = 1
}
}
```
**RST Mapping:**
```rst
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:**
```bash
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:**
```json
{
"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:**
```rst
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:**
```yaml
strategy:
matrix:
php: ['8.1', '8.2', '8.3']
typo3: ['12.4', '13.0']
database: ['mysqli', 'pdo_mysql']
```
**RST Mapping:**
```rst
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:**
```markdown
## [13.1.0] - 2024-12-01
### Added
- TYPO3 v13 compatibility
- New image processing options
### Fixed
- Image upload validation
```
**RST Mapping:**
```rst
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
```markdown
# 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
```rst
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:
```bash
#!/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:
```bash
#!/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:
```bash
#!/usr/bin/env bash
# Compare data/*.json with Documentation/**/*.rst
# Output: Documentation/ANALYSIS.md
```
### scripts/generate-templates.sh
Generate RST templates from extracted data:
```bash
#!/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
```
## 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/

335
skills/typo3-docs/references/intercept-deployment.md Normal file
View File

@@ -0,0 +1,335 @@
# TYPO3 Intercept Deployment & Webhook Setup
Complete guide for setting up automatic documentation deployment using TYPO3 Intercept webhooks.
## Overview
TYPO3 Intercept provides automatic documentation rendering and publishing for TYPO3 extensions. When properly configured, your documentation is automatically built and published to docs.typo3.org whenever you push commits or create version tags.
## Prerequisites
Before setting up webhooks, ensure:
1. **Extension Published in TER**: Your extension must be registered in the TYPO3 Extension Repository (TER) with the same extension key specified in `composer.json`
2. **Git Repository Referenced**: The Git repository URL must be listed on your extension's TER detail page
3. **Documentation Structure**: Your `Documentation/` directory must contain:
- `Index.rst` (main entry point)
- `Settings.cfg` (documentation metadata)
- Valid RST files following TYPO3 documentation standards
## Webhook Registration
### GitHub Setup
1. **Navigate to Repository Settings**
- Go to your GitHub repository
- Click **Settings** → **Webhooks**
- Click **Add webhook**
2. **Configure Webhook**
- **Payload URL**: `https://docs-hook.typo3.org`
- **Content type**: `application/json`
- **SSL verification**: Enable SSL verification
- **Which events**: Select "Just the push event"
- **Active**: Check the "Active" checkbox
3. **Save Webhook**
- Click **Add webhook** to save
- GitHub will send a test ping to verify connectivity
### GitLab Setup
1. **Navigate to Webhooks**
- Go to your GitLab project
- Click **Settings** → **Webhooks**
2. **Configure Webhook**
- **URL**: `https://docs-hook.typo3.org`
- **Trigger**: Check both:
- Push events
- Tag push events
- **SSL verification**: Enable SSL verification
3. **Add Webhook**
- Click **Add webhook** to save
- GitLab will test the connection
## First-Time Approval
The first time you trigger documentation rendering, the TYPO3 Documentation Team must approve your repository:
1. **Automatic Hold**: First webhook trigger is automatically placed on hold
2. **Manual Review**: Documentation Team reviews:
- TER registration matches composer.json extension key
- Git repository is properly referenced in TER
- Documentation structure is valid
3. **Approval**: Once approved, future builds are automatic
4. **Notification**: Check Intercept dashboard for approval status
**Typical Approval Time**: 1-3 business days
## Verification
### Check Webhook Delivery
**GitHub:**
1. Go to **Settings** → **Webhooks**
2. Click on the webhook
3. Scroll to **Recent Deliveries**
4. Verify delivery shows `200` response code
**GitLab:**
1. Go to **Settings** → **Webhooks**
2. Click **Edit** on the webhook
3. Scroll to **Recent events**
4. Verify event shows success status
### Check Intercept Dashboard
1. **Visit**: https://intercept.typo3.com/
2. **Check Recent Actions**: View recent webhook triggers
3. **Documentation Deployments**: https://intercept.typo3.com/admin/docs/deployments
4. **Search for Your Extension**: Filter by package name
### Verify Published Documentation
Once approved and rendered successfully:
**Published URL Pattern**:
```
https://docs.typo3.org/p/{vendor}/{extension}/{branch}/en-us/
```
**Example**:
```
https://docs.typo3.org/p/netresearch/rte-ckeditor-image/main/en-us/
```
**Version-Specific URLs**:
```
https://docs.typo3.org/p/{vendor}/{extension}/{version}/en-us/
```
## Triggering Documentation Builds
### Automatic Triggers
Documentation builds are triggered automatically by:
1. **Git Push to Main/Master**
```bash
git push origin main
```
2. **Version Tags**
```bash
git tag 2.1.0
git push origin 2.1.0
```
3. **Branch Push** (for multi-version documentation)
```bash
git push origin docs-v12
```
### Manual Trigger
If automatic builds fail or you need to rebuild:
1. Visit: https://intercept.typo3.com/admin/docs/deployments
2. Find your extension
3. Click **Redeploy** button
4. Monitor build progress in Recent actions
## Build Process
Understanding the rendering pipeline:
1. **Webhook Received**: Intercept receives push notification
2. **Queue Job**: Build job added to rendering queue
3. **Clone Repository**: Code checked out at specific commit/tag
4. **Render Documentation**: Using `ghcr.io/typo3-documentation/render-guides:latest`
5. **Publish**: Rendered HTML published to docs.typo3.org
6. **Index**: Documentation indexed for search
**Typical Build Time**: 2-5 minutes
## Troubleshooting
### Webhook Not Triggering
**Check**:
- Webhook URL is exactly `https://docs-hook.typo3.org`
- SSL verification is enabled
- Webhook is marked as "Active"
- Recent deliveries show `200` response
**Fix**:
1. Edit webhook settings
2. Verify URL and SSL settings
3. Click **Redeliver** on failed delivery
4. Check Intercept Recent actions
### Build Failing
**Common Issues**:
1. **RST Syntax Errors**
```bash
# Validate locally before pushing
~/.claude/skills/typo3-docs/scripts/validate_docs.sh
```
2. **Missing Settings.cfg**
```bash
# Check file exists
ls -la Documentation/Settings.cfg
```
3. **Invalid Cross-References**
- Render locally to check for broken `:ref:` links
- Fix undefined labels
4. **Encoding Issues**
- Ensure all files are UTF-8 encoded
- Check for BOM (Byte Order Mark) issues
### First Build Stuck "On Hold"
**Expected Behavior**: First build requires manual approval
**Action**:
- Wait for Documentation Team review (1-3 business days)
- Ensure TER registration is complete
- Verify Git repository URL in TER matches webhook source
**Speed Up Approval**:
- Post in TYPO3 Slack [#typo3-documentation](https://typo3.slack.com/archives/C028JEPJL)
- Reference your extension key and repository URL
### Documentation Not Updating
**Check**:
1. **Build Status**: Visit Intercept dashboard, verify build succeeded
2. **Cache**: Browser cache might show old version
- Hard refresh: `Ctrl+F5` / `Cmd+Shift+R`
- Try incognito/private mode
3. **Correct URL**: Verify you're visiting the right branch/version URL
**Fix**:
1. Trigger manual rebuild from Intercept dashboard
2. Check build logs for errors
3. Verify `Settings.cfg` has correct project configuration
## Best Practices
### Pre-Push Checklist
Before pushing documentation changes:
✅ **Validate RST Syntax**
```bash
~/.claude/skills/typo3-docs/scripts/validate_docs.sh /path/to/project
```
✅ **Render Locally**
```bash
~/.claude/skills/typo3-docs/scripts/render_docs.sh /path/to/project
open Documentation-GENERATED-temp/Index.html
```
✅ **Check for Warnings**
- No rendering warnings
- No broken cross-references
- All code blocks have language specified
- UTF-8 emoji icons render correctly
✅ **Commit Message**
```bash
git commit -m "docs: update configuration guide with new settings"
```
### Version Management
**Branching Strategy**:
- `main` / `master`: Latest development documentation
- Version tags: Specific release documentation (e.g., `2.1.0`, `3.0.0`)
- Version branches: Long-term support versions (e.g., `docs-v12`, `docs-v11`)
**Tag Documentation Builds**:
```bash
# Create release tag
git tag -a 2.1.0 -m "Release 2.1.0"
git push origin 2.1.0
# Documentation auto-builds for version 2.1.0
# Published at: /p/{vendor}/{ext}/2.1.0/en-us/
```
### Multi-Version Documentation
For supporting multiple TYPO3 versions:
1. **Create Version Branches**
```bash
git checkout -b docs-v12
git push origin docs-v12
```
2. **Configure Settings.cfg** for each branch
```ini
[general]
project = Extension Name
release = 2.1.0
version = 2.1
```
3. **Webhook Triggers All Branches**
- Pushes to any branch trigger builds
- Each branch published separately
## Security Considerations
### Webhook Secret (Optional)
While TYPO3 Intercept doesn't require webhook secrets, you can add them for extra security:
**GitHub**:
1. Generate random secret: `openssl rand -hex 20`
2. Add to webhook **Secret** field
3. Intercept validates using X-Hub-Signature header
**GitLab**:
1. Generate random secret
2. Add to webhook **Secret token** field
3. Intercept validates using X-Gitlab-Token header
### Access Control
**Documentation Repositories Should**:
- Be publicly readable (required for Intercept access)
- Limit push access to trusted contributors
- Use branch protection for `main`/`master`
- Require pull request reviews for documentation changes
**Avoid in Documentation**:
- API keys, passwords, secrets
- Internal URLs, server hostnames
- Sensitive configuration details
- Personal information
## Resources
**Official Documentation**:
- [How to Document - Webhook Setup](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/WritingDocForExtension/Webhook.html)
- [TYPO3 Intercept Dashboard](https://intercept.typo3.com/)
- [Documentation Deployments](https://intercept.typo3.com/admin/docs/deployments)
**Community Support**:
- TYPO3 Slack: [#typo3-documentation](https://typo3.slack.com/archives/C028JEPJL)
- TYPO3 Slack: [#typo3-cms](https://typo3.slack.com/archives/C025HCWGM)
**Related Guides**:
- [TYPO3 Documentation Standards](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/)
- [RST Syntax Reference](rst-syntax.md)
- [TYPO3 Directives Reference](typo3-directives.md)

309
skills/typo3-docs/references/rst-syntax.md Normal file
View File

@@ -0,0 +1,309 @@
# RST Syntax Reference
Complete reStructuredText syntax reference for TYPO3 documentation.
## Headings
```rst
=======================
Page title in sentence case
=======================
Section heading
===============
Subsection heading
------------------
Subsubsection heading
~~~~~~~~~~~~~~~~~~~~~
Paragraph heading
^^^^^^^^^^^^^^^^^
```
**Rules:**
- Page titles: `=` above and below (must match title length)
- Sections: `=` below
- Subsections: `-` below
- Subsubsections: `~` below
- Paragraphs: `^` below
- **CRITICAL**: Underline must be exactly the same length as the title text
- **SENTENCE CASE**: Use sentence case for all headlines, NOT title case
- ✅ Correct: "Mass approval on Crowdin", "API endpoints", "Best practices"
- ❌ Wrong: "Mass Approval On Crowdin", "API Endpoints", "Best Practices"
## Inline Formatting
```rst
*italic text*
**bold text**
``code or literal text``
```
## Code Blocks
**PHP:**
```rst
.. code-block:: php
<?php
$code = 'example';
```
**YAML:**
```rst
.. code-block:: yaml
setting: value
nested:
item: value
```
**TypoScript:**
```rst
.. code-block:: typoscript
config.tx_extension.setting = value
```
**Bash:**
```rst
.. code-block:: bash
composer install
```
**JavaScript:**
```rst
.. code-block:: javascript
const example = 'value';
```
## Lists
**Bullet Lists:**
```rst
- First item.
- Second item.
- Nested item.
- Another nested.
```
**Numbered Lists:**
```rst
1. First item.
2. Second item.
3. Third item.
```
**Definition Lists:**
```rst
term
Definition of the term.
another term
Definition of another term.
```
**Punctuation Rules:**
- **End with periods**: All list items should end with a period (`.`)
- ✅ Correct: `1. Retrieve project metadata to get available languages.`
- ❌ Wrong: `1. Retrieve project metadata to get available languages`
- Exception: Single-word or very short items may omit periods for readability
## Links
**External Links:**
```rst
`Link text <https://example.com>`__
```
**Internal Cross-References:**
```rst
.. _my-label:
Section Title
=============
Link to :ref:`my-label`
Link with custom text: :ref:`Custom Text <my-label>`
```
**Documentation Links:**
```rst
:ref:`t3tsref:start` (TYPO3 TS Reference)
:ref:`t3coreapi:start` (TYPO3 Core API)
```
## Tables
**Simple Table:**
```rst
=========== ===========
Column 1 Column 2
=========== ===========
Row 1 Col 1 Row 1 Col 2
Row 2 Col 1 Row 2 Col 2
=========== ===========
```
**Grid Table:**
```rst
+------------+------------+
| Header 1 | Header 2 |
+============+============+
| Cell 1 | Cell 2 |
+------------+------------+
```
**List Table:**
```rst
.. list-table:: Table Title
:header-rows: 1
:widths: 20 80
* - Column 1
- Column 2
* - Value 1
- Value 2
```
## Admonitions
```rst
.. note::
Additional information
.. important::
Important notice
.. warning::
Warning message
.. attention::
Attention required
.. tip::
Helpful tip
.. caution::
Caution advised
```
## Images
```rst
.. image:: ../Images/screenshot.png
:alt: Alternative text
:width: 600px
:class: with-shadow
```
**Figure with Caption:**
```rst
.. figure:: ../Images/screenshot.png
:alt: Alternative text
:width: 600px
This is the caption text
```
## Table of Contents
**In-page TOC:**
```rst
.. contents::
:local:
:depth: 2
```
**Toctree (document hierarchy):**
```rst
.. toctree::
:maxdepth: 2
:titlesonly:
:hidden:
Introduction/Index
Configuration/Index
API/Index
```
## Comments
```rst
.. This is a comment
It can span multiple lines
and will not appear in the output
```
## Line Blocks
```rst
| Line 1
| Line 2
| Line 3
```
## Substitutions
```rst
.. |TYPO3| replace:: TYPO3 CMS
Using |TYPO3| in documentation...
```
## Special Characters
```rst
\*literal asterisk\*
```
## Whitespace Rules
1. **Blank lines**: Required before and after directives
2. **Indentation**: Use 3 spaces for directive content
3. **No trailing whitespace**: Remove all trailing spaces
4. **Consistent indentation**: Maintain same level within blocks
## Common Mistakes
❌ **Wrong underline length:**
```rst
Section
==== # Too short
```
❌ **Missing blank lines:**
```rst
.. code-block:: php
$code = 'example'; # No blank line before content
```
❌ **Incorrect indentation:**
```rst
.. note::
Text # Only 2 spaces instead of 3
```
✅ **Correct:**
```rst
Section
=======
.. code-block:: php
$code = 'example';
.. note::
Text with 3-space indentation
```
## References
- **Sphinx RST Guide:** https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
- **Docutils RST:** https://docutils.sourceforge.io/rst.html
- **TYPO3 Documentation Guide:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/

509
skills/typo3-docs/references/typo3-directives.md Normal file
View File

@@ -0,0 +1,509 @@
# TYPO3-Specific Directives
Comprehensive reference for TYPO3-specific RST directives and extensions.
## Permalink Anchors (Labels)
Every section in TYPO3 documentation **MUST** have a permalink anchor (label) for deep linking.
**Syntax:**
```rst
.. _section-name-label:
Section heading
===============
```
**Requirements:**
- Place label **immediately before** the section heading (no blank line between)
- Use **lowercase** with hyphens (`-`) as separators
- Use **descriptive, hierarchical names** reflecting the document structure
- Labels enable `:ref:` cross-references and URL anchors
**Example from Mass Approval documentation:**
```rst
.. _crowdin-mass-approval:
========================
Mass approval on Crowdin
========================
.. _crowdin-mass-approval-workflow:
Crowdin API workflow
====================
.. _crowdin-mass-approval-api:
API endpoints
-------------
.. _crowdin-mass-approval-authentication:
Authentication
--------------
.. _crowdin-mass-approval-implementation:
PHP implementation
==================
.. _crowdin-mass-approval-implementation-usage:
Usage
-----
.. _crowdin-mass-approval-best-practices:
Best practices
==============
.. _crowdin-mass-approval-best-practices-error:
Error handling
--------------
```
**Naming Convention:**
- Start with document/topic prefix: `crowdin-mass-approval`
- Add section hierarchy: `crowdin-mass-approval-workflow`
- Add subsection: `crowdin-mass-approval-implementation-usage`
- This creates predictable, navigable anchor URLs
**Benefits:**
- Direct linking to specific sections
- Stable URLs for documentation references
- Cross-document `:ref:` linking
- Search engine indexability
## Configuration Values (confval)
Document configuration options with structured metadata.
**Basic Syntax:**
```rst
.. confval:: settingName
:type: boolean
:Default: true
:Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['setting']
Description of the configuration value.
```
**Field Types:**
- `:type:` - boolean, string, integer, array, object
- `:Default:` - Default value (capitalize 'Default')
- `:Path:` - Full path to the setting in TYPO3 configuration
- `:Scope:` - Where setting applies (frontend, backend, global)
**Example:**
```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.
```
**TSConfig Example:**
```rst
.. confval:: RTE.default.buttons.image.options.magic.maxWidth
:type: integer
:Default: 300
Maximum width in pixels for images inserted through the RTE.
Images exceeding this width will be automatically scaled down.
```
**YAML Configuration Example:**
```rst
.. confval:: editor.externalPlugins.typo3image.allowedExtensions
:type: string
:Default: Value from ``$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']``
Comma-separated list of allowed image file extensions for the CKEditor
image plugin. Overrides global TYPO3 image extension settings.
```
### Two-Level Configuration Pattern
**Pattern:** Site-wide configuration with per-item override capability
Many TYPO3 features support two-level configuration:
1. **Site-wide default** via TypoScript
2. **Per-item override** via attributes or UI
**When to use:**
- Features where editors need item-specific control
- Mixed content pages (some items use site-wide, others override)
- Configuration that varies by context or workflow
**Documentation Structure:**
```rst
## Configuration
The noScale feature can be configured at two levels:
1. **Site-wide (TypoScript)** - Default behavior for all images
2. **Per-image (Editor)** - Override for specific images
### Site-Wide Configuration
.. confval:: noScale
:type: boolean
:Default: false (auto-optimization enabled)
:Path: lib.parseFunc_RTE.tags.img.noScale
Controls whether images are automatically optimized or used as original files.
When enabled, all images skip TYPO3's image processing.
**Configuration Priority:**
- **Per-image setting** (data-noscale attribute) takes precedence
- **Site-wide setting** (TypoScript) is the fallback
- **Default behavior** when neither is set
**Enable for all images:**
.. code-block:: typoscript
:caption: setup.typoscript
lib.parseFunc_RTE {
tags.img {
noScale = 1 # All images use original files
}
}
### Per-Image Override
.. versionadded:: 13.0.0
Editors can now enable noScale for individual images using the CKEditor
image dialog, overriding the site-wide TypoScript setting.
**How to Use:**
1. Insert or edit an image in CKEditor
2. Open the image dialog (double-click or select + click insert image button)
3. Check "Use original file (noScale)" checkbox
4. Save the image
**Configuration Priority:**
- **Per-image setting** (data-noscale attribute) overrides site-wide configuration
- If unchecked: Falls back to site-wide TypoScript setting
- If no site-wide setting: Default behavior (auto-optimization)
**Workflow Benefits:**
- **Mixed Content**: Some images original, others optimized on same page
- **Editorial Control**: Editors decide per-image without developer intervention
- **Flexibility**: Override site-wide settings for specific images
- **Newsletter Integration**: Mark high-quality images for email
**Technical Implementation:**
.. code-block:: html
<!-- Per-image override via data attribute -->
<img src="image.jpg" data-noscale="true" />
```
**Example from t3x-rte_ckeditor_image:**
The noScale feature uses this pattern:
- **Site-wide**: `lib.parseFunc_RTE.tags.img.noScale = 1` in TypoScript
- **Per-image**: Checkbox in CKEditor dialog sets `data-noscale` attribute
- **Priority**: Per-image attribute overrides TypoScript setting
**Documentation Benefits:**
✅ Clear separation of site-wide vs per-item configuration
✅ Explicit priority/precedence rules documented
✅ Workflow guidance for editors
✅ Technical implementation details for developers
✅ Use case explanations (mixed content, newsletters)
## Version Information
Document version-specific changes with proper directives.
**Version Added:**
```rst
.. versionadded:: 13.0.0
The CKEditor plugin now requires ``StyleUtils`` and ``GeneralHtmlSupport``
dependencies for style functionality. Previous versions did not have this requirement.
```
**Version Changed:**
```rst
.. versionchanged:: 13.1.0
Image processing now uses TYPO3's native image processing service instead
of custom processing logic.
```
**Deprecated:**
```rst
.. deprecated:: 13.2.0
The ``oldSetting`` configuration option is deprecated. Use ``newSetting`` instead.
This option will be removed in version 14.0.0.
```
**Placement:** Place version directives immediately before or after the relevant content they describe.
## PHP Domain
Document PHP classes, methods, and properties.
**Class:**
```rst
.. php:class:: SelectImageController
Main controller for image selection wizard.
Extends: ``TYPO3\\CMS\\Backend\\Controller\\ElementBrowserController``
```
**Method:**
```rst
.. 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 or error response
:returntype: \\Psr\\Http\\Message\\ResponseInterface
:throws \\RuntimeException: When file is not found or invalid
```
**Property:**
```rst
.. php:attr:: resourceFactory
:type: \\TYPO3\\CMS\\Core\\Resource\\ResourceFactory
Resource factory for file operations.
```
**Namespace:**
```rst
.. php:namespace:: Netresearch\\RteCKEditorImage\\Controller
.. php:class:: SelectImageController
```
## Card Grids
Create visual card layouts for navigation.
**Basic Card Grid:**
```rst
.. card-grid::
:columns: 1
:columns-md: 2
:gap: 4
:card-height: 100
.. card:: 📘 Introduction
The RTE CKEditor Image extension provides comprehensive image handling
capabilities for CKEditor in TYPO3.
.. card-footer:: :ref:`Read more <introduction>`
:button-style: btn btn-primary stretched-link
.. card:: 🔧 Configuration
Learn how to configure the extension with TSConfig, YAML, and TypoScript
settings for your specific needs.
.. card-footer:: :ref:`Read more <configuration>`
:button-style: btn btn-secondary stretched-link
```
**Card Grid Options:**
- `:columns:` - Number of columns (default layout)
- `:columns-md:` - Columns for medium+ screens
- `:gap:` - Gap between cards (1-5)
- `:card-height:` - Card height (100 for equal height)
- `:class:` - Additional CSS classes
**Card Footer Styles:**
- `btn btn-primary stretched-link` - Primary button with full card click
- `btn btn-secondary stretched-link` - Secondary button with full card click
- `btn btn-light stretched-link` - Light button
**UTF-8 Emoji Icons:**
Use in card titles for visual appeal:
- 📘 Documentation
- 🔧 Configuration
- 🎨 Design
- 🔍 Search
- ⚡ Performance
- 🛡️ Security
- 📊 API
- 🆘 Troubleshooting
## Intersphinx References
Cross-reference TYPO3 core documentation.
**TSRef (TypoScript Reference):**
```rst
:ref:`t3tsref:start`
:ref:`t3tsref:stdwrap`
:ref:`t3tsref:cobj-image`
```
**Core API:**
```rst
:ref:`t3coreapi:start`
:ref:`t3coreapi:fal`
:ref:`t3coreapi:dependency-injection`
```
**TSConfig:**
```rst
:ref:`t3tsconfig:start`
:ref:`t3tsconfig:pagetsconfig`
```
**TCA:**
```rst
:ref:`t3tca:start`
:ref:`t3tca:columns-types`
```
**Fluid:**
```rst
:ref:`t3viewhelper:start`
:ref:`t3viewhelper:typo3-fluid-image`
```
## Index and Glossary
**Index Entry:**
```rst
.. index:: Image Processing, FAL, CKEditor
.. _image-processing:
Image Processing
================
```
**Glossary:**
```rst
.. glossary::
FAL
File Abstraction Layer - TYPO3's file management system
Magic Image
Automatically processed image with dimension constraints
```
**Reference Glossary:**
```rst
See :term:`FAL` for details.
```
## Tabs
Create tabbed content for multiple options.
```rst
.. tabs::
.. tab:: Composer
.. code-block:: bash
composer require netresearch/rte-ckeditor-image
.. tab:: Extension Manager
Install via TYPO3 Extension Manager:
1. Go to Admin Tools > Extensions
2. Search for "rte_ckeditor_image"
3. Click Install
```
## Special TYPO3 Directives
**Include Partial:**
```rst
.. include:: ../Includes.rst.txt
```
**File Tree:**
```rst
.. directory-tree::
* Classes/
* Controller/
* Database/
* Utils/
* Resources/
* Public/
* JavaScript/
```
**YouTube Video:**
```rst
.. youtube:: VIDEO_ID
```
**Download Link:**
```rst
:download:`Download PDF <../_static/manual.pdf>`
```
## Best Practices
1. **Use confval for all configuration**: Document every setting with proper metadata
2. **Version everything**: Add versionadded/versionchanged for all version-specific features
3. **Cross-reference liberally**: Link to related documentation with :ref:
4. **Card grids for navigation**: Use card-grid layouts for Index.rst files
5. **Emoji icons in titles**: Use UTF-8 emojis in card titles for visual appeal
6. **Stretched links**: Always use `stretched-link` class in card-footer for full card clicks
7. **PHP domain for APIs**: Document all public methods with php:method
8. **Intersphinx for core**: Reference TYPO3 core docs with intersphinx
## Quality Checklist
✅ All configuration options documented with confval
✅ Version information added for all version-specific features
✅ Cross-references work (no broken :ref: links)
✅ Card grids use stretched-link in card-footer
✅ UTF-8 emoji icons in card titles
✅ PHP API documented with php:method
✅ Code blocks specify language
✅ Admonitions used appropriately
✅ Local render shows no warnings
✅ All headings have proper underlines
✅ **Sentence case** used for all headlines (not Title Case)
✅ **Permalink anchors** (`.. _label:`) before every section heading
✅ **List punctuation**: all list items end with periods
✅ **CGL compliance**: PHP code examples pass `make fix-cgl`
## References
- **TYPO3 Documentation Guide:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
- **Confval Reference:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Confval.html
- **Version Directives:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Content/Versions.html
- **PHP Domain:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Code/Phpdomain.html
- **Card Grid:** https://sphinxcontrib-typo3-theme.readthedocs.io/en-us/latest/

532
skills/typo3-docs/references/typo3-extension-architecture.md Normal file
View File

@@ -0,0 +1,532 @@
# TYPO3 Extension Architecture Reference
Official TYPO3 extension file structure for documentation extraction weighting and categorization.
**Source:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Index.html
## File Structure Hierarchy
### 🔴 Required Files (High Priority)
**composer.json** - Composer configuration
- **Documentation Priority:** HIGH
- **Extract:** Package name, description, dependencies, autoload configuration
- **Map to RST:** Introduction/Index.rst (overview), Installation requirements
- **Weight:** Critical for dependency documentation
**ext_emconf.php** - Extension metadata
- **Documentation Priority:** HIGH
- **Extract:** Title, description, version, author, constraints
- **Map to RST:** Introduction/Index.rst, Settings.cfg
- **Weight:** Essential metadata, version constraints
**Index.rst** (in Documentation/)
- **Documentation Priority:** CRITICAL
- **Required:** Main documentation entry point
- **Must Exist:** For TYPO3 Intercept deployment
**Settings.cfg** (in Documentation/)
- **Documentation Priority:** CRITICAL
- **Required:** Documentation build configuration
- **Must Exist:** For TYPO3 Intercept deployment
### 🟡 Core Structure Files (Medium-High Priority)
**ext_localconf.php** - Runtime configuration
- **Documentation Priority:** MEDIUM-HIGH
- **Extract:** Plugin registrations, hooks, service configurations
- **Map to RST:** Integration guides, Developer/Configuration.rst
- **Weight:** Important for integration documentation
**ext_tables.php** - Backend configuration
- **Documentation Priority:** MEDIUM
- **Extract:** Backend module registrations, permissions
- **Map to RST:** Developer/Backend.rst
- **Weight:** Backend-specific documentation
**ext_tables.sql** - Database schema
- **Documentation Priority:** MEDIUM
- **Extract:** Table structures, field definitions
- **Map to RST:** Developer/Database.rst, API/DataModel.rst
- **Weight:** Important for database documentation
**ext_conf_template.txt** - Extension configuration template
- **Documentation Priority:** HIGH
- **Extract:** All configuration options, types, defaults, security warnings
- **Map to RST:** Integration/Configuration.rst (confval directives)
- **Weight:** Critical - direct user-facing configuration
## Directory Structure Weights
### Classes/ (Weight: HIGH)
**Purpose:** PHP source code following PSR-4 autoloading
**Priority Hierarchy:**
1. **Classes/Controller/** (Weight: HIGH)
- **Documentation Priority:** HIGH
- **Extract:** Action methods, parameters, return types
- **Map to RST:** API/Controllers/, Developer/Plugins.rst
- **Pattern:** MVC controllers extending `ActionController`
2. **Classes/Domain/Model/** (Weight: HIGH)
- **Documentation Priority:** HIGH
- **Extract:** Entity properties, getters/setters, relationships
- **Map to RST:** API/Models/, Developer/DataModel.rst
- **Pattern:** Extbase domain models
3. **Classes/Domain/Repository/** (Weight: MEDIUM-HIGH)
- **Documentation Priority:** MEDIUM-HIGH
- **Extract:** Query methods, custom finders
- **Map to RST:** API/Repositories/, Developer/DataAccess.rst
- **Pattern:** Extends `\TYPO3\CMS\Extbase\Persistence\Repository`
4. **Classes/ViewHelpers/** (Weight: MEDIUM)
- **Documentation Priority:** MEDIUM
- **Extract:** ViewHelper arguments, usage examples
- **Map to RST:** Developer/ViewHelpers.rst
- **Pattern:** Custom Fluid ViewHelpers
5. **Classes/Utility/** (Weight: MEDIUM)
- **Documentation Priority:** MEDIUM
- **Extract:** Utility methods, static helpers
- **Map to RST:** API/Utilities/
- **Pattern:** Static helper classes
6. **Classes/Service/** (Weight: MEDIUM-HIGH)
- **Documentation Priority:** MEDIUM-HIGH
- **Extract:** Service methods, dependencies
- **Map to RST:** API/Services/
- **Pattern:** Business logic services
### Configuration/ (Weight: VERY HIGH)
**Purpose:** All TYPO3 configuration files
**Priority Hierarchy:**
1. **Configuration/TCA/** (Weight: VERY HIGH)
- **Documentation Priority:** VERY HIGH
- **Extract:** Table definitions, field configurations, relationships
- **Map to RST:** Developer/DataModel.rst, Editor/Fields.rst
- **Files:** `<tablename>.php`
- **Pattern:** Database table configuration arrays
2. **Configuration/TCA/Overrides/** (Weight: HIGH)
- **Documentation Priority:** HIGH
- **Extract:** Field additions, modifications to core tables
- **Map to RST:** Integration/CoreExtensions.rst
- **Files:** `<tablename>.php`
- **Pattern:** TCA modifications
3. **Configuration/TypoScript/** (Weight: HIGH)
- **Documentation Priority:** HIGH
- **Extract:** Constants, setup, plugin configurations
- **Map to RST:** Configuration/TypoScript.rst
- **Files:** `constants.typoscript`, `setup.typoscript`
- **Pattern:** TypoScript configuration
4. **Configuration/Sets/** (Weight: HIGH)
- **Documentation Priority:** HIGH
- **Extract:** Site set configurations, settings definitions
- **Map to RST:** Configuration/SiteSets.rst
- **Files:** `config.yaml`, `settings.definitions.yaml`, `setup.typoscript`
- **Pattern:** Modern configuration approach (TYPO3 v13+)
5. **Configuration/TsConfig/** (Weight: MEDIUM-HIGH)
- **Documentation Priority:** MEDIUM-HIGH
- **Extract:** Page TSconfig, User TSconfig
- **Map to RST:** Editor/PageTSconfig.rst, Editor/UserTSconfig.rst
- **Subdirs:** `Page/`, `User/`
- **Files:** `*.tsconfig`
6. **Configuration/Backend/** (Weight: MEDIUM)
- **Documentation Priority:** MEDIUM
- **Extract:** Backend routes, modules, AJAX routes
- **Map to RST:** Developer/Backend.rst
- **Files:** `Routes.php`, `Modules.php`, `AjaxRoutes.php`
7. **Configuration/Services.yaml** (Weight: HIGH)
- **Documentation Priority:** HIGH
- **Extract:** DI configuration, event listeners, console commands
- **Map to RST:** Developer/DependencyInjection.rst, Developer/Events.rst
- **Pattern:** Symfony-style service configuration
8. **Configuration/Extbase/Persistence/Classes.php** (Weight: MEDIUM)
- **Documentation Priority:** MEDIUM
- **Extract:** Model-to-table mappings
- **Map to RST:** Developer/Persistence.rst
9. **Configuration/Icons.php** (Weight: LOW)
- **Documentation Priority:** LOW
- **Extract:** Icon identifiers
- **Map to RST:** Developer/Icons.rst (if comprehensive)
### Resources/ (Weight: MEDIUM)
**Purpose:** Asset files and templates
**Priority Hierarchy:**
1. **Resources/Private/Language/** (Weight: MEDIUM-HIGH)
- **Documentation Priority:** MEDIUM
- **Extract:** Translation keys (for reference)
- **Map to RST:** Developer/Localization.rst
- **Files:** `*.xlf` (XLIFF format)
- **Note:** Extract labels for API documentation context
2. **Resources/Private/Templates/** (Weight: MEDIUM)
- **Documentation Priority:** MEDIUM
- **Extract:** Template structure (for developer reference)
- **Map to RST:** Developer/Templating.rst
- **Files:** `[ControllerName]/[ActionName].html`
- **Note:** Document template variables and ViewHelpers used
3. **Resources/Private/Layouts/** (Weight: LOW-MEDIUM)
- **Documentation Priority:** LOW
- **Extract:** Layout structure
- **Files:** `*.html`
4. **Resources/Private/Partials/** (Weight: LOW-MEDIUM)
- **Documentation Priority:** LOW
- **Extract:** Reusable template fragments
- **Files:** `*.html`
5. **Resources/Public/** (Weight: LOW)
- **Documentation Priority:** LOW
- **Extract:** Public asset information (if relevant)
- **Subdirs:** `CSS/`, `JavaScript/`, `Icons/`, `Images/`
- **Note:** Usually not documented in detail
### Documentation/ (Weight: CRITICAL)
**Purpose:** Official RST documentation
**Required Files:**
- `Index.rst` - Main entry point
- `Settings.cfg` - Build configuration
**Common Structure:**
- `Introduction/` - Overview, features, screenshots
- `Installation/` - Installation and upgrade
- `Configuration/` - TypoScript, extension settings
- `Integration/` - Integration with other extensions
- `Editor/` - User guide for editors
- `Developer/` - Developer documentation
- `API/` - PHP API reference
- `Troubleshooting/` - Common issues
**Priority:** CRITICAL - This is the primary output target for extraction
### Tests/ (Weight: LOW)
**Purpose:** Unit, functional, and acceptance tests
**Documentation Priority:** LOW
- Extract test class names for coverage documentation
- Generally not documented in user-facing docs
- May reference in Developer/Testing.rst if test examples provided
**Structure:**
- `Tests/Unit/` - Unit tests
- `Tests/Functional/` - Functional tests
- `Tests/Acceptance/` - Acceptance tests (Codeception)
## Extraction Weight Matrix
### Primary Sources (Extract First)
```
Priority 1 - CRITICAL (Must Document):
├─ ext_emconf.php → Extension metadata
├─ ext_conf_template.txt → User configuration
├─ composer.json → Dependencies
└─ Configuration/TCA/*.php → Data model
Priority 2 - HIGH (Should Document):
├─ Classes/Controller/ → Controllers/Actions
├─ Classes/Domain/Model/ → Domain entities
├─ Classes/Service/ → Business logic
├─ Configuration/TypoScript/ → TypoScript config
├─ Configuration/Sets/ → Site sets (v13+)
└─ ext_localconf.php → Runtime registration
Priority 3 - MEDIUM (Consider Documenting):
├─ Classes/Domain/Repository/ → Data access
├─ Classes/ViewHelpers/ → Custom ViewHelpers
├─ Configuration/Backend/ → Backend modules
├─ Configuration/TsConfig/ → TSconfig
├─ Configuration/Services.yaml → DI/Events
└─ Resources/Private/Language/ → Translation context
```
### Secondary Sources (Extract If Needed)
```
Priority 4 - MEDIUM-LOW:
├─ Classes/Utility/ → Utility functions
├─ ext_tables.php → Backend config
├─ ext_tables.sql → Database schema
└─ Configuration/TCA/Overrides/ → Core extensions
Priority 5 - LOW:
├─ Resources/Private/Templates/ → Template structure
├─ Resources/Public/ → Public assets
├─ Tests/ → Test coverage
└─ Configuration/Icons.php → Icon registry
```
## Documentation Mapping Strategy
### Extension Metadata → Introduction
**Source:** `ext_emconf.php`, `composer.json`, `README.md`
**Target:** `Documentation/Introduction/Index.rst`
**Extract:**
- Extension title → Main heading
- Description → First paragraph
- Version → Version marker
- Author → Credits section
- Constraints → Requirements section
**Example Mapping:**
```
ext_emconf.php:
'title' => 'CKEditor Image Support'
'version' => '13.1.0'
'constraints' => ['typo3' => '12.4-13.5']
→ Introduction/Index.rst:
========================
CKEditor Image Support
========================
:Version: 13.1.0
:Language: en
Requirements
------------
- TYPO3: 12.4 - 13.5
```
### Configuration Options → Integration/Configuration
**Source:** `ext_conf_template.txt`
**Target:** `Documentation/Integration/Configuration.rst`
**Extract Pattern:**
```
# cat=category; type=boolean; label=Label: Description
settingName = defaultValue
→ .. confval:: settingName
:type: boolean
:Default: defaultValue
:Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['settingName']
Description text here
```
**Security Warnings:** Extract and map to `.. warning::` directive
### PHP Classes → API Documentation
**Source:** `Classes/**/*.php`
**Target:** `Documentation/API/[ClassName].rst`
**Mapping by Type:**
**Controllers:**
```php
Classes/Controller/UserController.php
→ API/UserController.rst
.. php:class:: UserController
User management controller
.. php:method:: listAction(): ResponseInterface
```
**Models:**
```php
Classes/Domain/Model/User.php
→ API/User.rst
.. php:class:: User
User domain model
.. php:attr:: username
:type: string
```
**Repositories:**
```php
Classes/Domain/Repository/UserRepository.php
→ API/UserRepository.rst
.. php:class:: UserRepository
User data repository
.. php:method:: findByEmail(string $email): ?User
```
### TCA Configuration → Developer/DataModel
**Source:** `Configuration/TCA/*.php`
**Target:** `Documentation/Developer/DataModel.rst`
**Extract:**
- Table name → Section heading
- ctrl['title'] → Table title
- columns → Field documentation
**Example:**
```php
Configuration/TCA/tx_myext_domain_model_user.php:
'ctrl' => ['title' => 'User']
'columns' => [
'username' => [...],
'email' => [...]
]
→ Developer/DataModel.rst:
Users Table
===========
Database table: tx_myext_domain_model_user
Fields
------
username
User login name
email
User email address
```
### TypoScript → Configuration/TypoScript
**Source:** `Configuration/TypoScript/*.typoscript`
**Target:** `Documentation/Configuration/TypoScript.rst`
**Extract:**
- Constants → Configuration reference
- Setup → Implementation examples
## Quality Weighting Algorithm
### Documentation Coverage Score
```
Score = (P1_documented / P1_total) * 0.5 +
(P2_documented / P2_total) * 0.3 +
(P3_documented / P3_total) * 0.15 +
(P4_documented / P4_total) * 0.05
Where:
P1 = Priority 1 (CRITICAL) items
P2 = Priority 2 (HIGH) items
P3 = Priority 3 (MEDIUM) items
P4 = Priority 4+ (LOW) items
```
### Gap Analysis Priority
```
Priority = BaseWeight * Severity * UserImpact
BaseWeight (from file structure):
ext_conf_template.txt config = 10
Controllers = 9
Models = 9
TCA = 8
ext_emconf.php = 8
Services = 7
Repositories = 6
ViewHelpers = 5
Utilities = 4
Severity:
Missing completely = 3
Outdated (wrong defaults) = 2
Incomplete (missing examples) = 1
UserImpact:
User-facing (config, editor features) = 3
Integrator-facing (TypoScript, TSconfig) = 2
Developer-facing (API) = 1
```
### Example Calculation
```
Missing confval for "fetchExternalImages":
Priority = 10 (ext_conf_template) * 3 (missing) * 3 (user-facing) = 90
Outdated Controller documentation:
Priority = 9 (controller) * 2 (outdated) * 1 (developer) = 18
Missing Utility documentation:
Priority = 4 (utility) * 3 (missing) * 1 (developer) = 12
```
**Action:** Document in priority order: 90 → 18 → 12
## Official Structure Validation
### Required Structure Checklist
**Composer-Mode Installation:**
- ✅ `composer.json` with `"type": "typo3-cms-extension"`
- ✅ PSR-4 autoload configuration
- ✅ `Documentation/Index.rst`
- ✅ `Documentation/Settings.cfg`
**Classic-Mode Installation:**
- ✅ `ext_emconf.php`
- ✅ `Documentation/Index.rst`
- ✅ `Documentation/Settings.cfg`
### Reserved Prefixes
**Root Directory:**
- `ext_*` files are reserved for TYPO3 system use
- Only allowed: `ext_emconf.php`, `ext_localconf.php`, `ext_tables.php`, `ext_tables.sql`, `ext_conf_template.txt`
**Never Create:**
- `ext_custom.php`
- `ext_myconfig.php`
- Any other `ext_*` files
## Best Practices for Extraction
1. **Follow Official Structure:** Extract based on official TYPO3 architecture
2. **Weight by Location:** Use file location to determine documentation priority
3. **Respect Conventions:** Map to RST sections based on TYPO3 conventions
4. **Security First:** Extract and highlight security warnings from configs
5. **Version Awareness:** Track version-specific features from ext_emconf.php
6. **Dependency Mapping:** Use composer.json and constraints for requirements
7. **Complete Coverage:** Prioritize user-facing config, controllers, models
8. **Context Awareness:** Understand file purpose from directory structure
## Resources
- **Official Structure:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/
- **TCA Reference:** https://docs.typo3.org/m/typo3/reference-tca/
- **TypoScript Reference:** https://docs.typo3.org/m/typo3/reference-typoscript/
- **Extbase/Fluid:** https://docs.typo3.org/m/typo3/book-extbasefluid/

71
skills/typo3-docs/scripts/add-agents-md.sh Executable file
View File

@@ -0,0 +1,71 @@
#!/usr/bin/env bash
#
# Add AGENTS.md to Documentation/ folder
#
# This script creates an AGENTS.md file in the Documentation/ directory
# to provide context for AI assistants working with TYPO3 documentation.
#
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Script configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
PROJECT_DIR="$(pwd)"
DOC_DIR="${PROJECT_DIR}/Documentation"
AGENTS_FILE="${DOC_DIR}/AGENTS.md"
echo -e "${GREEN}=== Add AGENTS.md to Documentation/ ===${NC}"
echo
# Check if Documentation directory exists
if [ ! -d "${DOC_DIR}" ]; then
echo -e "${RED}Error: Documentation/ directory not found${NC}"
echo "Current directory: ${PROJECT_DIR}"
echo "Please run this script from your TYPO3 extension root directory"
exit 1
fi
# Check if AGENTS.md already exists
if [ -f "${AGENTS_FILE}" ]; then
echo -e "${YELLOW}⚠ AGENTS.md already exists in Documentation/${NC}"
echo
read -p "Do you want to overwrite it? (y/N) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "Aborted."
exit 0
fi
fi
# Copy AGENTS.md template
echo -e "${YELLOW}Creating AGENTS.md from template...${NC}"
cp "${SKILL_DIR}/templates/AGENTS.md" "${AGENTS_FILE}"
echo -e "${GREEN}✓ Created ${AGENTS_FILE}${NC}"
echo
echo "Next steps:"
echo "1. Edit Documentation/AGENTS.md to customize:"
echo " - Documentation Strategy section"
echo " - Target Audience"
echo " - Main Topics"
echo
echo "2. The AGENTS.md file provides context for AI assistants:"
echo " - TYPO3 RST syntax and directives"
echo " - Documentation structure patterns"
echo " - Rendering and validation procedures"
echo " - Cross-reference patterns"
echo
echo "3. This file helps AI assistants:"
echo " - Understand documentation purpose and audience"
echo " - Apply correct RST syntax and TYPO3 directives"
echo " - Follow documentation best practices"
echo " - Navigate the documentation structure"

357
skills/typo3-docs/scripts/analyze-docs.sh Executable file
View File

@@ -0,0 +1,357 @@
#!/usr/bin/env bash
#
# Analyze Documentation Coverage
#
# Compares extracted data with existing Documentation/ to identify:
# - Missing documentation
# - Outdated documentation
# - Inconsistencies
#
# Generates: Documentation/ANALYSIS.md
#
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
DOC_DIR="${PROJECT_DIR}/Documentation"
ANALYSIS_FILE="${DOC_DIR}/ANALYSIS.md"
# TYPO3 Official Architecture Weights (from typo3-extension-architecture.md)
# BaseWeight for gap priority calculation: Priority = BaseWeight * Severity * UserImpact
# File Type Weights
declare -A BASE_WEIGHTS=(
["ext_conf_template"]=10 # User-facing configuration
["controller"]=9 # Core application logic
["model"]=9 # Domain entities
["tca"]=8 # Database configuration
["ext_emconf"]=8 # Extension metadata
["service"]=7 # Business logic
["repository"]=6 # Data access
["viewhelper"]=5 # Template helpers
["utility"]=4 # Helper functions
["other"]=3 # Miscellaneous
)
# Severity Multipliers
SEVERITY_MISSING=3 # Completely undocumented
SEVERITY_OUTDATED=2 # Exists but wrong/incomplete
SEVERITY_INCOMPLETE=1 # Partial documentation
# User Impact Multipliers
IMPACT_USER=3 # End users, editors
IMPACT_INTEGRATOR=2 # TypoScript, TSconfig
IMPACT_DEVELOPER=1 # API, internal code
# Function to calculate gap priority
# Usage: calculate_priority <base_weight> <severity> <impact>
calculate_priority() {
local base_weight=$1
local severity=$2
local impact=$3
echo $((base_weight * severity * impact))
}
# Function to determine class type from file path
get_class_type() {
local file_path=$1
if [[ "$file_path" == *"Controller"* ]]; then
echo "controller"
elif [[ "$file_path" == *"Domain/Model"* ]]; then
echo "model"
elif [[ "$file_path" == *"Domain/Repository"* ]]; then
echo "repository"
elif [[ "$file_path" == *"Service"* ]]; then
echo "service"
elif [[ "$file_path" == *"ViewHelper"* ]]; then
echo "viewhelper"
elif [[ "$file_path" == *"Utility"* ]]; then
echo "utility"
else
echo "other"
fi
}
echo -e "${GREEN}=== Documentation Coverage Analysis ===${NC}"
echo
# Check if Documentation/ exists
if [ ! -d "${DOC_DIR}" ]; then
echo -e "${YELLOW}No Documentation/ directory found${NC}"
echo "Run this from a TYPO3 extension root directory"
exit 1
fi
# Check if extraction data exists
if [ ! -d "${DATA_DIR}" ]; then
echo -e "${YELLOW}No extraction data found${NC}"
echo "Run scripts/extract-all.sh first"
exit 1
fi
echo "Project: ${PROJECT_DIR}"
echo "Documentation: ${DOC_DIR}"
echo "Extraction Data: ${DATA_DIR}"
echo
# Start analysis report
cat > "${ANALYSIS_FILE}" <<'EOF'
# Documentation Analysis Report
**Generated:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")
## Summary
This report compares extracted project data with existing documentation to identify gaps and inconsistencies.
EOF
# Replace the date placeholder
sed -i "s/\$(date -u +\"%Y-%m-%d %H:%M:%S UTC\")/$(date -u +"%Y-%m-%d %H:%M:%S UTC")/g" "${ANALYSIS_FILE}"
# Analyze PHP APIs
echo -e "${BLUE}Analyzing PHP APIs...${NC}"
if [ -f "${DATA_DIR}/php_apis.json" ]; then
total_classes=$(jq '.classes | length' "${DATA_DIR}/php_apis.json" 2>/dev/null || echo 0)
# Count documented classes (look for .rst files in API/ or Developer/)
documented_classes=0
if [ -d "${DOC_DIR}/API" ] || [ -d "${DOC_DIR}/Developer" ]; then
documented_classes=$(find "${DOC_DIR}" -name "*.rst" -type f -exec grep -l ".. php:class::" {} \; 2>/dev/null | wc -l)
fi
missing_classes=$((total_classes - documented_classes))
cat >> "${ANALYSIS_FILE}" <<EOF
### PHP Classes
- **Total Classes:** ${total_classes}
- **Documented Classes:** ${documented_classes}
- **Missing Documentation:** ${missing_classes}
EOF
if [ $missing_classes -gt 0 ]; then
echo "## Missing Class Documentation" >> "${ANALYSIS_FILE}"
echo >> "${ANALYSIS_FILE}"
echo "Classes listed by **priority score** (Priority = BaseWeight × Severity × Impact)" >> "${ANALYSIS_FILE}"
echo >> "${ANALYSIS_FILE}"
# Create temporary file with priority calculations
temp_classes=$(mktemp)
# Extract classes with priority calculations
jq -r '.classes[] | @json' "${DATA_DIR}/php_apis.json" 2>/dev/null | while IFS= read -r class_json; do
file_path=$(echo "$class_json" | jq -r '.file')
class_type=$(get_class_type "$file_path")
base_weight=${BASE_WEIGHTS[$class_type]}
priority=$(calculate_priority $base_weight $SEVERITY_MISSING $IMPACT_DEVELOPER)
echo "$priority|$class_json" >> "$temp_classes"
done
# Sort by priority (descending) and output formatted
sort -t'|' -k1 -rn "$temp_classes" 2>/dev/null | while IFS='|' read -r priority class_json; do
namespace=$(echo "$class_json" | jq -r '.namespace')
name=$(echo "$class_json" | jq -r '.name')
file=$(echo "$class_json" | jq -r '.file')
desc=$(echo "$class_json" | jq -r '.description')
cat >> "${ANALYSIS_FILE}" <<CLASSEOF
### ${namespace}\\${name}
- **Priority Score:** ${priority} ⚠️
- **File:** \`${file}\`
- **Type:** ${class_type}
- **Description:** ${desc}
- **Suggested Location:** \`Documentation/API/${name}.rst\`
CLASSEOF
done
rm -f "$temp_classes"
fi
echo " Classes: ${documented_classes}/${total_classes} documented"
fi
# Analyze Configuration Options
echo -e "${BLUE}Analyzing Configuration Options...${NC}"
if [ -f "${DATA_DIR}/config_options.json" ]; then
total_options=$(jq '.config_options | length' "${DATA_DIR}/config_options.json" 2>/dev/null || echo 0)
# Count documented confval directives
documented_options=0
if find "${DOC_DIR}" -name "*.rst" -type f -exec grep -q ".. confval::" {} \; 2>/dev/null; then
documented_options=$(find "${DOC_DIR}" -name "*.rst" -type f -exec grep ".. confval::" {} \; 2>/dev/null | wc -l)
fi
missing_options=$((total_options - documented_options))
cat >> "${ANALYSIS_FILE}" <<EOF
### Configuration Options
- **Total Options:** ${total_options}
- **Documented Options:** ${documented_options}
- **Missing Documentation:** ${missing_options}
EOF
if [ $missing_options -gt 0 ]; then
echo "## Missing Configuration Documentation" >> "${ANALYSIS_FILE}"
echo >> "${ANALYSIS_FILE}"
echo "Configuration options listed by **priority score** (Priority = BaseWeight × Severity × Impact)" >> "${ANALYSIS_FILE}"
echo >> "${ANALYSIS_FILE}"
# Configuration options are user-facing (HIGH priority)
base_weight=${BASE_WEIGHTS["ext_conf_template"]}
priority=$(calculate_priority $base_weight $SEVERITY_MISSING $IMPACT_USER)
# List undocumented options with priority
jq -r --arg priority "$priority" '.config_options[] |
"### " + .key + "\n\n" +
"- **Priority Score:** " + $priority + " 🚨\n" +
"- **Type:** " + .type + "\n" +
"- **Default:** `" + .default + "`\n" +
"- **Description:** " + .description + "\n" +
(if .security_warning then "- **⚠️ Security Warning:** " + .security_warning + "\n" else "" end) +
"- **Suggested Location:** `Documentation/Integration/Configuration.rst`\n\n" +
"**Template:**\n\n```rst\n" +
".. confval:: " + .key + "\n\n" +
" :type: " + .type + "\n" +
" :Default: " + .default + "\n" +
" :Path: $GLOBALS['"'"'TYPO3_CONF_VARS'"'"']['"'"'EXTENSIONS'"'"']['"'"'ext_key'"'"']['"'"'" + .key + "'"'"']\n\n" +
" " + .description + "\n" +
(if .security_warning then "\n .. warning::\n " + .security_warning + "\n" else "" end) +
"```\n"' \
"${DATA_DIR}/config_options.json" 2>/dev/null >> "${ANALYSIS_FILE}" || true
fi
echo " Options: ${documented_options}/${total_options} documented"
fi
# Check Extension Metadata
echo -e "${BLUE}Analyzing Extension Metadata...${NC}"
if [ -f "${DATA_DIR}/extension_meta.json" ]; then
ext_version=$(jq -r '.metadata.version // "unknown"' "${DATA_DIR}/extension_meta.json" 2>/dev/null)
ext_title=$(jq -r '.metadata.title // "unknown"' "${DATA_DIR}/extension_meta.json" 2>/dev/null)
cat >> "${ANALYSIS_FILE}" <<EOF
### Extension Metadata
- **Title:** ${ext_title}
- **Version:** ${ext_version}
- **Location:** Check `Documentation/Index.rst` and `Documentation/Settings.cfg`
**Recommended Actions:**
- Verify version number in Settings.cfg matches ext_emconf.php
- Ensure extension title is documented in Index.rst
- Check TYPO3/PHP version constraints are in Installation requirements
EOF
echo " Extension: ${ext_title} v${ext_version}"
fi
# Priority Score Explanation
cat >> "${ANALYSIS_FILE}" <<'EOF'
## Priority Score System
Documentation gaps are ranked using **TYPO3 Official Architecture Weighting**:
```
Priority = BaseWeight × Severity × UserImpact
```
### Base Weights (by file type)
- **Configuration (ext_conf_template.txt):** 10 - User-facing settings
- **Controllers:** 9 - Core application logic
- **Models:** 9 - Domain entities
- **TCA:** 8 - Database configuration
- **Services:** 7 - Business logic
- **Repositories:** 6 - Data access
- **ViewHelpers:** 5 - Template helpers
- **Utilities:** 4 - Helper functions
### Severity Multipliers
- **Missing (3):** No documentation exists
- **Outdated (2):** Documentation exists but incorrect
- **Incomplete (1):** Partial documentation
### User Impact Multipliers
- **End Users (3):** Editors, content creators
- **Integrators (2):** TypoScript, TSconfig users
- **Developers (1):** PHP API users
### Example Calculations
- Missing config option: `10 × 3 × 3 = 90` 🚨 (HIGHEST)
- Missing controller: `9 × 3 × 1 = 27` ⚠️
- Missing utility: `4 × 3 × 1 = 12`
**Reference:** See `references/typo3-extension-architecture.md`
## Recommendations
Items above are **already sorted by priority score**. Focus on highest scores first.
### Immediate Actions (Priority Score ≥50)
1. **Document configuration options** (Score: 90) - Critical for users
2. **Document controllers and models** (Score: 27) - Essential for developers
### Quality Improvements
1. Run validation: `scripts/validate_docs.sh`
2. Render locally: `scripts/render_docs.sh`
3. Fix any rendering warnings or broken cross-references
### Enhancements
1. Add usage examples for all configuration options
2. Add code examples for all API methods
3. Consider adding screenshots for user-facing features
## Next Steps
1. **Review this analysis** - Focus on highest priority scores first
2. **Manual documentation** - Create missing RST files using provided templates
3. **Validate** - `scripts/validate_docs.sh`
4. **Render** - `scripts/render_docs.sh`
5. **Commit** - Add new documentation to version control
---
**Analysis Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")
**Extraction Data:** See `.claude/docs-extraction/data/`
**Weighting Source:** TYPO3 Official Extension Architecture
EOF
# Replace date placeholder again
sed -i "s/\$(date -u +\"%Y-%m-%d %H:%M:%S UTC\")/$(date -u +"%Y-%m-%d %H:%M:%S UTC")/g" "${ANALYSIS_FILE}"
echo
echo -e "${GREEN}=== Analysis Complete ===${NC}"
echo
echo "Report generated: ${ANALYSIS_FILE}"
echo
echo -e "${YELLOW}Review the analysis report for documentation gaps and recommendations.${NC}"
echo

158
skills/typo3-docs/scripts/extract-all.sh Executable file
View File

@@ -0,0 +1,158 @@
#!/usr/bin/env bash
#
# Extract All Documentation Data
#
# Orchestrates extraction from all available sources:
# - PHP source code
# - Extension configuration
# - TYPO3 configuration
# - Composer dependencies
# - Project files (README, CHANGELOG)
# - Build configurations (optional)
# - Repository metadata (optional)
#
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
# Script configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
PROJECT_DIR="$(pwd)"
EXTRACTION_DIR="${PROJECT_DIR}/.claude/docs-extraction"
DATA_DIR="${EXTRACTION_DIR}/data"
CACHE_DIR="${EXTRACTION_DIR}/cache"
echo -e "${GREEN}=== TYPO3 Documentation Extraction ===${NC}"
echo
echo "Project: ${PROJECT_DIR}"
echo "Extraction Directory: ${EXTRACTION_DIR}"
echo
# Create directories
mkdir -p "${DATA_DIR}"
mkdir -p "${CACHE_DIR}"
# Extraction flags
EXTRACT_BUILD=false
EXTRACT_REPO=false
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--build)
EXTRACT_BUILD=true
shift
;;
--repo)
EXTRACT_REPO=true
shift
;;
--all)
EXTRACT_BUILD=true
EXTRACT_REPO=true
shift
;;
-h|--help)
echo "Usage: $0 [OPTIONS]"
echo
echo "Options:"
echo " --build Include build configuration extraction (.github, phpunit.xml, etc.)"
echo " --repo Include repository metadata extraction (requires network)"
echo " --all Extract everything (build + repo)"
echo " -h, --help Show this help message"
exit 0
;;
*)
echo -e "${RED}Unknown option: $1${NC}"
exit 1
;;
esac
done
# Core extractions (always run)
echo -e "${BLUE}Running core extractions...${NC}"
echo
# 1. PHP Code
echo -e "${YELLOW}→ Extracting PHP code...${NC}"
if "${SCRIPT_DIR}/extract-php.sh"; then
echo -e "${GREEN}✓ PHP extraction complete${NC}"
else
echo -e "${RED}✗ PHP extraction failed${NC}"
fi
echo
# 2. Extension Configuration
echo -e "${YELLOW}→ Extracting extension configuration...${NC}"
if "${SCRIPT_DIR}/extract-extension-config.sh"; then
echo -e "${GREEN}✓ Extension config extraction complete${NC}"
else
echo -e "${RED}✗ Extension config extraction failed${NC}"
fi
echo
# 3. Composer Dependencies
echo -e "${YELLOW}→ Extracting composer dependencies...${NC}"
if "${SCRIPT_DIR}/extract-composer.sh"; then
echo -e "${GREEN}✓ Composer extraction complete${NC}"
else
echo -e "${RED}✗ Composer extraction failed${NC}"
fi
echo
# 4. Project Files
echo -e "${YELLOW}→ Extracting project files...${NC}"
if "${SCRIPT_DIR}/extract-project-files.sh"; then
echo -e "${GREEN}✓ Project files extraction complete${NC}"
else
echo -e "${RED}✗ Project files extraction failed${NC}"
fi
echo
# Optional extractions
if [ "$EXTRACT_BUILD" = true ]; then
echo -e "${BLUE}Running build configuration extraction...${NC}"
echo
echo -e "${YELLOW}→ Extracting build configs...${NC}"
if "${SCRIPT_DIR}/extract-build-configs.sh"; then
echo -e "${GREEN}✓ Build config extraction complete${NC}"
else
echo -e "${RED}✗ Build config extraction failed${NC}"
fi
echo
fi
if [ "$EXTRACT_REPO" = true ]; then
echo -e "${BLUE}Running repository metadata extraction...${NC}"
echo
echo -e "${YELLOW}→ Extracting repository metadata...${NC}"
if "${SCRIPT_DIR}/extract-repo-metadata.sh"; then
echo -e "${GREEN}✓ Repository metadata extraction complete${NC}"
else
echo -e "${RED}✗ Repository metadata extraction failed (network or auth issue?)${NC}"
fi
echo
fi
# Summary
echo -e "${GREEN}=== Extraction Complete ===${NC}"
echo
echo "Extracted data saved to: ${DATA_DIR}"
echo
echo "Next steps:"
echo "1. Review extracted data: ls -lh ${DATA_DIR}"
echo "2. Run gap analysis: ${SCRIPT_DIR}/analyze-docs.sh"
echo "3. Generate RST templates: ${SCRIPT_DIR}/generate-templates.sh"
echo "4. Review templates: Documentation/GENERATED/"
echo

89
skills/typo3-docs/scripts/extract-build-configs.sh Executable file
View File

@@ -0,0 +1,89 @@
#!/usr/bin/env bash
#
# Extract Build Configuration
#
# Extracts configuration from:
# - .github/workflows/*.yml (GitHub Actions)
# - .gitlab-ci.yml (GitLab CI)
# - phpunit.xml (PHPUnit config)
# - phpstan.neon (PHPStan config)
#
set -e
# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
OUTPUT_FILE="${DATA_DIR}/build_configs.json"
mkdir -p "${DATA_DIR}"
echo "Extracting build configurations..."
# Start JSON
echo '{' > "${OUTPUT_FILE}"
echo ' "extraction_date": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",' >> "${OUTPUT_FILE}"
# GitHub Actions
if [ -d "${PROJECT_DIR}/.github/workflows" ]; then
workflow_files=$(find "${PROJECT_DIR}/.github/workflows" -name "*.yml" -o -name "*.yaml" 2>/dev/null || true)
if [ -n "$workflow_files" ]; then
echo ' "github_actions": {' >> "${OUTPUT_FILE}"
echo ' "exists": true,' >> "${OUTPUT_FILE}"
echo ' "files": [' >> "${OUTPUT_FILE}"
first=true
for wf in $workflow_files; do
if [ "$first" = false ]; then echo ' ,' >> "${OUTPUT_FILE}"; fi
first=false
rel_path="${wf#$PROJECT_DIR/}"
echo ' "'${rel_path}'"' >> "${OUTPUT_FILE}"
done
echo ' ]' >> "${OUTPUT_FILE}"
echo ' },' >> "${OUTPUT_FILE}"
else
echo ' "github_actions": { "exists": false },' >> "${OUTPUT_FILE}"
fi
else
echo ' "github_actions": { "exists": false },' >> "${OUTPUT_FILE}"
fi
# GitLab CI
if [ -f "${PROJECT_DIR}/.gitlab-ci.yml" ]; then
echo ' "gitlab_ci": { "exists": true, "file": ".gitlab-ci.yml" },' >> "${OUTPUT_FILE}"
else
echo ' "gitlab_ci": { "exists": false },' >> "${OUTPUT_FILE}"
fi
# PHPUnit
phpunit_files=$(find "${PROJECT_DIR}" -maxdepth 2 -name "phpunit.xml*" 2>/dev/null || true)
if [ -n "$phpunit_files" ]; then
echo ' "phpunit": { "exists": true, "files": [' >> "${OUTPUT_FILE}"
first=true
for pf in $phpunit_files; do
if [ "$first" = false ]; then echo ' ,' >> "${OUTPUT_FILE}"; fi
first=false
rel_path="${pf#$PROJECT_DIR/}"
echo ' "'${rel_path}'"' >> "${OUTPUT_FILE}"
done
echo ' ] },' >> "${OUTPUT_FILE}"
else
echo ' "phpunit": { "exists": false },' >> "${OUTPUT_FILE}"
fi
# PHPStan
if [ -f "${PROJECT_DIR}/phpstan.neon" ] || [ -f "${PROJECT_DIR}/phpstan.neon.dist" ]; then
echo ' "phpstan": { "exists": true }' >> "${OUTPUT_FILE}"
else
echo ' "phpstan": { "exists": false }' >> "${OUTPUT_FILE}"
fi
# Close JSON
echo '}' >> "${OUTPUT_FILE}"
echo -e "${GREEN}✓ Build configs extracted: ${OUTPUT_FILE}${NC}"

61
skills/typo3-docs/scripts/extract-composer.sh Executable file
View File

@@ -0,0 +1,61 @@
#!/usr/bin/env bash
#
# Extract Composer Dependencies
#
# Extracts dependency information from composer.json
#
set -e
# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
COMPOSER_FILE="${PROJECT_DIR}/composer.json"
OUTPUT_FILE="${DATA_DIR}/dependencies.json"
mkdir -p "${DATA_DIR}"
if [ ! -f "${COMPOSER_FILE}" ]; then
echo -e "${YELLOW}No composer.json found, skipping${NC}"
echo '{"dependencies": {}}' > "${OUTPUT_FILE}"
exit 0
fi
echo "Extracting composer.json..."
# Extract relevant sections using jq if available, otherwise use PHP
if command -v jq &> /dev/null; then
jq '{
extraction_date: now | todate,
name: .name,
description: .description,
type: .type,
require: .require,
"require-dev": (."require-dev" // {}),
autoload: .autoload,
scripts: (.scripts // {})
}' "${COMPOSER_FILE}" > "${OUTPUT_FILE}"
else
# Fallback to PHP
php -r "
\$data = json_decode(file_get_contents('${COMPOSER_FILE}'), true);
echo json_encode([
'extraction_date' => date('c'),
'name' => \$data['name'] ?? '',
'description' => \$data['description'] ?? '',
'type' => \$data['type'] ?? '',
'require' => \$data['require'] ?? [],
'require-dev' => \$data['require-dev'] ?? [],
'autoload' => \$data['autoload'] ?? [],
'scripts' => \$data['scripts'] ?? []
], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
" > "${OUTPUT_FILE}"
fi
echo -e "${GREEN}✓ composer.json extracted: ${OUTPUT_FILE}${NC}"

123
skills/typo3-docs/scripts/extract-extension-config.sh Executable file
View File

@@ -0,0 +1,123 @@
#!/usr/bin/env bash
#
# Extract Extension Configuration
#
# Extracts metadata and configuration from:
# - ext_emconf.php (extension metadata)
# - ext_conf_template.txt (configuration options)
#
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
EXT_EMCONF="${PROJECT_DIR}/ext_emconf.php"
EXT_CONF_TEMPLATE="${PROJECT_DIR}/ext_conf_template.txt"
mkdir -p "${DATA_DIR}"
# Extract ext_emconf.php
if [ -f "${EXT_EMCONF}" ]; then
echo "Extracting ext_emconf.php..."
OUTPUT_FILE="${DATA_DIR}/extension_meta.json"
# Use PHP to parse ext_emconf.php properly
php -r "
\$_EXTKEY = 'temp';
include '${EXT_EMCONF}';
echo json_encode([
'extraction_date' => date('c'),
'metadata' => \$EM_CONF[\$_EXTKEY] ?? []
], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
" > "${OUTPUT_FILE}"
echo -e "${GREEN}✓ ext_emconf.php extracted: ${OUTPUT_FILE}${NC}"
else
echo -e "${YELLOW}No ext_emconf.php found, skipping${NC}"
fi
# Extract ext_conf_template.txt
if [ -f "${EXT_CONF_TEMPLATE}" ]; then
echo "Extracting ext_conf_template.txt..."
OUTPUT_FILE="${DATA_DIR}/config_options.json"
# Parse ext_conf_template.txt format:
# # cat=category/subcategory; type=type; label=Label: Description
# settingName = defaultValue
echo '{' > "${OUTPUT_FILE}"
echo ' "extraction_date": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",' >> "${OUTPUT_FILE}"
echo ' "config_options": [' >> "${OUTPUT_FILE}"
first=true
while IFS= read -r line; do
# Check if comment line with metadata
if [[ $line =~ ^#\ cat= ]]; then
# Extract metadata from comment
category=$(echo "$line" | sed -n 's/.*cat=\([^/;]*\).*/\1/p')
subcategory=$(echo "$line" | sed -n 's/.*cat=[^/]*\/\([^;]*\).*/\1/p')
type=$(echo "$line" | sed -n 's/.*type=\([^;]*\).*/\1/p')
label_and_desc=$(echo "$line" | sed -n 's/.*label=\(.*\)/\1/p')
label=$(echo "$label_and_desc" | cut -d':' -f1)
description=$(echo "$label_and_desc" | cut -d':' -f2- | sed 's/^ *//')
# Check for WARNING in description
security_warning=""
if echo "$description" | grep -qi "WARNING:"; then
security_warning=$(echo "$description" | sed -n 's/.*WARNING: \(.*\)/\1/p')
description=$(echo "$description" | sed 's/WARNING:.*//' | sed 's/ *$//')
fi
# Read next line for setting name and default
read -r next_line
if [[ $next_line =~ ^([^=]+)\ =\ (.+)$ ]]; then
setting_name="${BASH_REMATCH[1]}"
setting_name=$(echo "$setting_name" | sed 's/ *$//')
default_value="${BASH_REMATCH[2]}"
default_value=$(echo "$default_value" | sed 's/^ *//;s/ *$//')
# Add comma for non-first entries
if [ "$first" = false ]; then
echo ' ,' >> "${OUTPUT_FILE}"
fi
first=false
# Write JSON entry
echo ' {' >> "${OUTPUT_FILE}"
echo ' "key": "'${setting_name}'",' >> "${OUTPUT_FILE}"
echo ' "category": "'${category}'",' >> "${OUTPUT_FILE}"
echo ' "subcategory": "'${subcategory}'",' >> "${OUTPUT_FILE}"
echo ' "type": "'${type}'",' >> "${OUTPUT_FILE}"
echo ' "label": "'"${label}"'",' >> "${OUTPUT_FILE}"
echo ' "description": "'"${description}"'",' >> "${OUTPUT_FILE}"
echo ' "default": "'"${default_value}"'"' >> "${OUTPUT_FILE}"
if [ -n "$security_warning" ]; then
echo ' ,' >> "${OUTPUT_FILE}"
echo ' "security_warning": "'"${security_warning}"'"' >> "${OUTPUT_FILE}"
fi
echo -n ' }' >> "${OUTPUT_FILE}"
fi
fi
done < "${EXT_CONF_TEMPLATE}"
# Close JSON
echo >> "${OUTPUT_FILE}"
echo ' ]' >> "${OUTPUT_FILE}"
echo '}' >> "${OUTPUT_FILE}"
echo -e "${GREEN}✓ ext_conf_template.txt extracted: ${OUTPUT_FILE}${NC}"
else
echo -e "${YELLOW}No ext_conf_template.txt found, skipping${NC}"
fi

152
skills/typo3-docs/scripts/extract-php.sh Executable file
View File

@@ -0,0 +1,152 @@
#!/usr/bin/env bash
#
# Extract PHP Code Documentation
#
# Parses PHP files in Classes/ directory to extract:
# - Class names, namespaces, descriptions
# - Method signatures and docblocks
# - Constants with descriptions
# - Security-critical comments
#
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
OUTPUT_FILE="${DATA_DIR}/php_apis.json"
CLASSES_DIR="${PROJECT_DIR}/Classes"
# TYPO3 Architecture Documentation Priorities
# Based on references/typo3-extension-architecture.md
get_doc_priority() {
local file_path=$1
if [[ "$file_path" == *"Controller"* ]]; then
echo "HIGH"
elif [[ "$file_path" == *"Domain/Model"* ]]; then
echo "HIGH"
elif [[ "$file_path" == *"Domain/Repository"* ]]; then
echo "MEDIUM-HIGH"
elif [[ "$file_path" == *"Service"* ]]; then
echo "MEDIUM-HIGH"
elif [[ "$file_path" == *"ViewHelper"* ]]; then
echo "MEDIUM"
elif [[ "$file_path" == *"Utility"* ]]; then
echo "MEDIUM"
else
echo "MEDIUM"
fi
}
get_class_category() {
local file_path=$1
if [[ "$file_path" == *"Controller"* ]]; then
echo "controller"
elif [[ "$file_path" == *"Domain/Model"* ]]; then
echo "model"
elif [[ "$file_path" == *"Domain/Repository"* ]]; then
echo "repository"
elif [[ "$file_path" == *"Service"* ]]; then
echo "service"
elif [[ "$file_path" == *"ViewHelper"* ]]; then
echo "viewhelper"
elif [[ "$file_path" == *"Utility"* ]]; then
echo "utility"
else
echo "other"
fi
}
# Check if Classes/ exists
if [ ! -d "${CLASSES_DIR}" ]; then
echo -e "${YELLOW}No Classes/ directory found, skipping PHP extraction${NC}"
echo '{"classes": []}' > "${OUTPUT_FILE}"
exit 0
fi
# Create output directory
mkdir -p "${DATA_DIR}"
echo "Scanning PHP files in: ${CLASSES_DIR}"
# Initialize JSON output
echo '{' > "${OUTPUT_FILE}"
echo ' "extraction_date": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",' >> "${OUTPUT_FILE}"
echo ' "classes": [' >> "${OUTPUT_FILE}"
# Find all PHP files
php_files=$(find "${CLASSES_DIR}" -type f -name "*.php" | sort)
file_count=$(echo "$php_files" | wc -l)
current=0
for php_file in $php_files; do
current=$((current + 1))
rel_path="${php_file#$PROJECT_DIR/}"
echo " Processing: ${rel_path} (${current}/${file_count})"
# Extract class information using grep and sed
# This is a simplified extraction - full parsing would require PHP parser
# Get namespace
namespace=$(grep -m 1 '^namespace ' "$php_file" | sed 's/namespace //;s/;//' || echo "")
# Get class name
class_name=$(grep -m 1 '^class \|^final class \|^abstract class ' "$php_file" | \
sed 's/^class //;s/^final class //;s/^abstract class //;s/ extends.*//;s/ implements.*//;s/{//;s/ //g' || echo "")
if [ -z "$class_name" ]; then
continue
fi
# Get class docblock (simplified - just get the first /** */ block)
class_desc=$(awk '/\/\*\*/{flag=1;next}/\*\//{flag=0}flag' "$php_file" | head -20 | grep -v '^ \* @' | sed 's/^ \* //;s/^ \*$//' | tr '\n' ' ' | sed 's/ */ /g;s/^ //;s/ $//')
# Get author
author=$(grep '@author' "$php_file" | head -1 | sed 's/.*@author //;s/ *$//' || echo "")
# Get license
license=$(grep '@license' "$php_file" | head -1 | sed 's/.*@license //;s/ *$//' || echo "")
# Get documentation priority
doc_priority=$(get_doc_priority "$rel_path")
class_category=$(get_class_category "$rel_path")
# Build JSON entry (simplified structure)
if [ $current -gt 1 ]; then
echo ' ,' >> "${OUTPUT_FILE}"
fi
echo ' {' >> "${OUTPUT_FILE}"
echo ' "name": "'${class_name}'",' >> "${OUTPUT_FILE}"
echo ' "namespace": "'${namespace}'",' >> "${OUTPUT_FILE}"
echo ' "file": "'${rel_path}'",' >> "${OUTPUT_FILE}"
echo ' "description": "'${class_desc}'",' >> "${OUTPUT_FILE}"
echo ' "author": "'${author}'",' >> "${OUTPUT_FILE}"
echo ' "license": "'${license}'",' >> "${OUTPUT_FILE}"
echo ' "documentation_priority": "'${doc_priority}'",' >> "${OUTPUT_FILE}"
echo ' "category": "'${class_category}'"' >> "${OUTPUT_FILE}"
echo -n ' }' >> "${OUTPUT_FILE}"
done
# Close JSON
echo >> "${OUTPUT_FILE}"
echo ' ]' >> "${OUTPUT_FILE}"
echo '}' >> "${OUTPUT_FILE}"
echo -e "${GREEN}✓ PHP extraction complete: ${OUTPUT_FILE}${NC}"
echo " Found ${file_count} PHP files"
# NOTE: This is a simplified extractor using bash/grep/sed
# For production use, consider using:
# - nikic/php-parser (PHP)
# - phpdocumentor/reflection-docblock (PHP)
# - Python script with libcst or ast

71
skills/typo3-docs/scripts/extract-project-files.sh Executable file
View File

@@ -0,0 +1,71 @@
#!/usr/bin/env bash
#
# Extract Project Files
#
# Extracts content from:
# - README.md
# - CHANGELOG.md
# - CONTRIBUTING.md (if exists)
#
set -e
# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
OUTPUT_FILE="${DATA_DIR}/project_files.json"
mkdir -p "${DATA_DIR}"
echo "Extracting project files..."
# Start JSON
echo '{' > "${OUTPUT_FILE}"
echo ' "extraction_date": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",' >> "${OUTPUT_FILE}"
# Extract README.md
if [ -f "${PROJECT_DIR}/README.md" ]; then
echo ' "readme": {' >> "${OUTPUT_FILE}"
echo ' "exists": true,' >> "${OUTPUT_FILE}"
echo ' "path": "README.md",' >> "${OUTPUT_FILE}"
# Get first 100 lines as preview
readme_content=$(head -100 "${PROJECT_DIR}/README.md" | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
echo ' "content_preview": "'${readme_content}'"' >> "${OUTPUT_FILE}"
echo ' },' >> "${OUTPUT_FILE}"
else
echo ' "readme": { "exists": false },' >> "${OUTPUT_FILE}"
fi
# Extract CHANGELOG.md
if [ -f "${PROJECT_DIR}/CHANGELOG.md" ]; then
echo ' "changelog": {' >> "${OUTPUT_FILE}"
echo ' "exists": true,' >> "${OUTPUT_FILE}"
echo ' "path": "CHANGELOG.md",' >> "${OUTPUT_FILE}"
# Get first 50 lines as preview
changelog_content=$(head -50 "${PROJECT_DIR}/CHANGELOG.md" | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
echo ' "content_preview": "'${changelog_content}'"' >> "${OUTPUT_FILE}"
echo ' },' >> "${OUTPUT_FILE}"
else
echo ' "changelog": { "exists": false },' >> "${OUTPUT_FILE}"
fi
# Extract CONTRIBUTING.md
if [ -f "${PROJECT_DIR}/CONTRIBUTING.md" ]; then
echo ' "contributing": {' >> "${OUTPUT_FILE}"
echo ' "exists": true,' >> "${OUTPUT_FILE}"
echo ' "path": "CONTRIBUTING.md"' >> "${OUTPUT_FILE}"
echo ' }' >> "${OUTPUT_FILE}"
else
echo ' "contributing": { "exists": false }' >> "${OUTPUT_FILE}"
fi
# Close JSON
echo '}' >> "${OUTPUT_FILE}"
echo -e "${GREEN}✓ Project files extracted: ${OUTPUT_FILE}${NC}"

141
skills/typo3-docs/scripts/extract-repo-metadata.sh Executable file
View File

@@ -0,0 +1,141 @@
#!/usr/bin/env bash
#
# Extract Repository Metadata
#
# Extracts metadata from GitHub or GitLab using CLI tools:
# - Repository description, topics, stats
# - Recent releases
# - Contributors
# - Open issues (optionally)
#
set -e
# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'
# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
CACHE_DIR="${PROJECT_DIR}/.claude/docs-extraction/cache"
OUTPUT_FILE="${DATA_DIR}/repo_metadata.json"
CACHE_FILE="${CACHE_DIR}/repo_metadata.json"
mkdir -p "${DATA_DIR}"
mkdir -p "${CACHE_DIR}"
# Check cache (24 hour TTL)
if [ -f "${CACHE_FILE}" ]; then
cache_age=$(($(date +%s) - $(stat -c %Y "${CACHE_FILE}" 2>/dev/null || stat -f %m "${CACHE_FILE}" 2>/dev/null || echo 0)))
if [ $cache_age -lt 86400 ]; then
echo -e "${YELLOW}Using cached repository metadata (${cache_age}s old)${NC}"
cp "${CACHE_FILE}" "${OUTPUT_FILE}"
exit 0
fi
fi
# Detect repository type
if git remote -v 2>/dev/null | grep -q github.com; then
REPO_TYPE="github"
REPO_URL=$(git remote -v | grep github.com | head -1 | sed 's/.*github.com[:/]\(.*\)\.git.*/\1/')
elif git remote -v 2>/dev/null | grep -q gitlab.com; then
REPO_TYPE="gitlab"
REPO_URL=$(git remote -v | grep gitlab.com | head -1 | sed 's/.*gitlab.com[:/]\(.*\)\.git.*/\1/')
else
echo -e "${YELLOW}No GitHub/GitLab remote found, skipping repository metadata${NC}"
echo '{"repository": {"exists": false}}' > "${OUTPUT_FILE}"
exit 0
fi
echo "Detected ${REPO_TYPE} repository: ${REPO_URL}"
# Extract based on repository type
if [ "$REPO_TYPE" = "github" ]; then
# Check if gh CLI is available
if ! command -v gh &> /dev/null; then
echo -e "${YELLOW}gh CLI not found, skipping GitHub metadata${NC}"
echo '{"repository": {"exists": false, "reason": "gh CLI not installed"}}' > "${OUTPUT_FILE}"
exit 0
fi
echo "Extracting GitHub metadata..."
# Get repository info
gh api "repos/${REPO_URL}" --jq '{
extraction_date: now | todate,
repository: {
type: "github",
name: .name,
full_name: .full_name,
description: .description,
topics: .topics,
stars: .stargazers_count,
forks: .forks_count,
open_issues: .open_issues_count,
created_at: .created_at,
updated_at: .updated_at,
homepage: .homepage
}
}' > "${OUTPUT_FILE}"
# Get releases
gh api "repos/${REPO_URL}/releases?per_page=5" --jq 'map({
tag: .tag_name,
name: .name,
published_at: .published_at,
prerelease: .prerelease
})' > /tmp/releases.json
# Get contributors
gh api "repos/${REPO_URL}/contributors?per_page=10" --jq 'map({
login: .login,
contributions: .contributions
})' > /tmp/contributors.json
# Merge into output file
jq --slurpfile releases /tmp/releases.json --slurpfile contributors /tmp/contributors.json \
'. + {releases: $releases[0], contributors: $contributors[0]}' "${OUTPUT_FILE}" > /tmp/merged.json
mv /tmp/merged.json "${OUTPUT_FILE}"
# Clean up temp files
rm -f /tmp/releases.json /tmp/contributors.json
echo -e "${GREEN}✓ GitHub metadata extracted: ${OUTPUT_FILE}${NC}"
elif [ "$REPO_TYPE" = "gitlab" ]; then
# Check if glab CLI is available
if ! command -v glab &> /dev/null; then
echo -e "${YELLOW}glab CLI not found, skipping GitLab metadata${NC}"
echo '{"repository": {"exists": false, "reason": "glab CLI not installed"}}' > "${OUTPUT_FILE}"
exit 0
fi
echo "Extracting GitLab metadata..."
# Get repository info
glab api "projects/$(echo ${REPO_URL} | sed 's/\//%2F/g')" --jq '{
extraction_date: now | todate,
repository: {
type: "gitlab",
name: .name,
full_name: .path_with_namespace,
description: .description,
topics: .topics,
stars: .star_count,
forks: .forks_count,
open_issues: .open_issues_count,
created_at: .created_at,
updated_at: .last_activity_at
}
}' > "${OUTPUT_FILE}"
echo -e "${GREEN}✓ GitLab metadata extracted: ${OUTPUT_FILE}${NC}"
fi
# Cache the result
cp "${OUTPUT_FILE}" "${CACHE_FILE}"
echo "Cached metadata for 24 hours"

41
skills/typo3-docs/scripts/render_docs.sh Executable file
View File

@@ -0,0 +1,41 @@
#!/usr/bin/env bash
#
# Render TYPO3 documentation locally using Docker
#
# Usage: ./render_docs.sh [project_root]
#
set -e
PROJECT_ROOT="${1:-.}"
if [ ! -d "$PROJECT_ROOT/Documentation" ]; then
echo "Error: Documentation/ directory not found at $PROJECT_ROOT"
echo "Usage: $0 [project_root]"
exit 1
fi
echo "🚀 Rendering TYPO3 documentation..."
echo " Project: $PROJECT_ROOT"
docker run --rm \
-v "$(cd "$PROJECT_ROOT" && pwd)":/project \
ghcr.io/typo3-documentation/render-guides:latest \
--config=Documentation
OUTPUT_DIR="$PROJECT_ROOT/Documentation-GENERATED-temp"
if [ -f "$OUTPUT_DIR/Index.html" ]; then
echo ""
echo "✅ Documentation rendered successfully!"
echo " Output: $OUTPUT_DIR/Index.html"
echo ""
echo "To view:"
echo " open $OUTPUT_DIR/Index.html"
echo " # or"
echo " xdg-open $OUTPUT_DIR/Index.html"
else
echo ""
echo "❌ Rendering failed or output not found"
exit 1
fi

121
skills/typo3-docs/scripts/validate_docs.sh Executable file
View File

@@ -0,0 +1,121 @@
#!/usr/bin/env bash
#
# Validate TYPO3 documentation RST files
#
# Usage: ./validate_docs.sh [project_root]
#
set -e
PROJECT_ROOT="${1:-.}"
DOC_DIR="$PROJECT_ROOT/Documentation"
if [ ! -d "$DOC_DIR" ]; then
echo "Error: Documentation/ directory not found at $PROJECT_ROOT"
echo "Usage: $0 [project_root]"
exit 1
fi
echo "🔍 Validating TYPO3 documentation..."
echo " Directory: $DOC_DIR"
echo ""
# Check for RST files
RST_FILES=$(find "$DOC_DIR" -name "*.rst" 2>/dev/null | wc -l)
if [ "$RST_FILES" -eq 0 ]; then
echo "❌ No RST files found in Documentation/"
exit 1
fi
echo "Found $RST_FILES RST files"
echo ""
# Check for Settings.cfg
if [ ! -f "$DOC_DIR/Settings.cfg" ]; then
echo "⚠️ Warning: Settings.cfg not found"
echo " This file is required for TYPO3 Intercept builds"
fi
# Check for Index.rst
if [ ! -f "$DOC_DIR/Index.rst" ]; then
echo "❌ Error: Index.rst not found"
echo " This is the main entry point and is required"
exit 1
fi
echo "✅ Index.rst found"
# Validate RST syntax if rst2html.py is available
if command -v rst2html.py &> /dev/null; then
echo ""
echo "Checking RST syntax..."
ERRORS=0
while IFS= read -r -d '' file; do
if ! rst2html.py --strict "$file" > /dev/null 2>&1; then
echo "❌ Syntax error in: $file"
((ERRORS++))
fi
done < <(find "$DOC_DIR" -name "*.rst" -print0)
if [ $ERRORS -eq 0 ]; then
echo "✅ All RST files have valid syntax"
else
echo ""
echo "❌ Found $ERRORS files with syntax errors"
exit 1
fi
else
echo "⚠️ rst2html.py not found - skipping syntax validation"
echo " Install with: pip install docutils"
fi
# Check for common issues
echo ""
echo "Checking for common issues..."
# Check for broken internal references (basic check)
WARNINGS=0
# Check for :ref: without proper labels
while IFS= read -r -d '' file; do
if grep -q ':ref:`[^<]*`' "$file"; then
REF_COUNT=$(grep -o ':ref:`[^`]*`' "$file" | wc -l)
if [ "$REF_COUNT" -gt 0 ]; then
echo "ℹ️ Found $REF_COUNT :ref: references in $(basename "$file")"
fi
fi
done < <(find "$DOC_DIR" -name "*.rst" -print0)
# Check for UTF-8 encoding
while IFS= read -r -d '' file; do
if ! file -b --mime-encoding "$file" | grep -q utf-8; then
echo "⚠️ Non-UTF-8 encoding in: $file"
((WARNINGS++))
fi
done < <(find "$DOC_DIR" -name "*.rst" -print0)
# Check for trailing whitespace
while IFS= read -r -d '' file; do
if grep -q '[[:space:]]$' "$file"; then
echo "⚠️ Trailing whitespace in: $file"
((WARNINGS++))
fi
done < <(find "$DOC_DIR" -name "*.rst" -print0)
echo ""
if [ $WARNINGS -eq 0 ]; then
echo "✅ No common issues found"
else
echo "⚠️ Found $WARNINGS warnings (not blocking)"
fi
echo ""
echo "Validation summary:"
echo " RST files: $RST_FILES"
echo " Warnings: $WARNINGS"
echo ""
echo "✅ Documentation validation complete"
echo ""
echo "Next step: Render locally to check for broken references"
echo " ./render_docs.sh $PROJECT_ROOT"

430
skills/typo3-docs/templates/AGENTS.md Normal file
View File

@@ -0,0 +1,430 @@
# 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
- `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:
```rst
.. confval:: myOption
:name: ext-myext-myoption
:type: string
:Default: 'default value'
Description of the configuration option.
```
### Version Documentation
Document version-specific features:
```rst
.. 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:
```rst
.. 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:
```rst
.. 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
```rst
.. _my-section-label:
Section Title
=============
Reference it with :ref:`my-section-label` or :ref:`custom text <my-section-label>`
```
### External TYPO3 Docs
```rst
:ref:`t3coreapi:caching` - Reference to TYPO3 Core API docs
:ref:`t3tsref:stdwrap` - Reference to TypoScript Reference
```
### Code References
```rst
:php:`ClassName` - PHP class
:ts:`config.tx_myext` - TypoScript
:file:`Configuration/TCA/` - File path
:bash:`composer require` - Shell command
```
## RST Syntax Patterns
### Headings
```rst
=============
Document Title (Level 1 - only once per file)
=============
Section (Level 2)
=================
Subsection (Level 3)
--------------------
Subsubsection (Level 4)
^^^^^^^^^^^^^^^^^^^^^^^
```
### Lists
```rst
Bullet list:
* Item 1
* Item 2
Numbered list:
#. First
#. Second
Definition list:
Term
Definition of the term.
```
### Code Blocks
```rst
.. code-block:: php
<?php
$variable = 'value';
.. code-block:: typoscript
plugin.tx_myext {
setting = value
}
```
### Admonitions
```rst
.. note::
Important information for users.
.. warning::
Critical warning about potential issues.
.. tip::
Helpful suggestion or best practice.
```
## Local Rendering
### Render Documentation
```bash
# 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
```bash
# 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
```ini
[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**
```bash
# 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**
```bash
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:**
```bash
cat .claude/docs-extraction/data/config_options.json | jq '.config_options[] | select(.key=="fetchExternalImages")'
```
**Create documentation:**
```rst
.. 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:**
```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:**
```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](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/)
- [RST Syntax Reference](~/.claude/skills/typo3-docs/references/rst-syntax.md)
- [TYPO3 Directives](~/.claude/skills/typo3-docs/references/typo3-directives.md)
- [Card Grids](~/.claude/skills/typo3-docs/references/card-grids.md)
- [Cross-References](~/.claude/skills/typo3-docs/references/cross-references.md)
- [Local Rendering](~/.claude/skills/typo3-docs/references/local-rendering.md)