commit 58302db858efef305fe295ad6710a72d3be75094 Author: Zhongwei Li Date: Sun Nov 30 08:43:30 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..af42e98 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "typo3-docs", + "description": "Create and maintain TYPO3 extension documentation following official TYPO3 documentation standards. Includes automated documentation extraction with priority-weighted gap analysis based on TYPO3 architecture, RST syntax reference, TYPO3-specific directives, local rendering, validation, and TYPO3 Intercept deployment setup.", + "version": "1.3.0-20251126", + "author": { + "name": "Netresearch DTT GmbH", + "email": "info@netresearch.de" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b3caf51 --- /dev/null +++ b/.gitignore @@ -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/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..414cd3b --- /dev/null +++ b/LICENSE @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..d934399 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# typo3-docs + +Create and maintain TYPO3 extension documentation following official TYPO3 documentation standards. Includes automated documentation extraction with priority-weighted gap analysis based on TYPO3 architecture, RST syntax reference, TYPO3-specific directives, local rendering, validation, and TYPO3 Intercept deployment setup. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..0ed3932 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,1123 @@ +--- +name: typo3-docs +version: 1.3.0 +description: > + Create and maintain TYPO3 extension documentation following official TYPO3 13.x standards. + + Trigger when: creating/editing Documentation/**/*.rst files or README.md (keep in sync!), using TYPO3 directives + (confval, versionadded, versionchanged, php:method, card-grid), rendering documentation locally (ddev docs, + render_docs.sh), extracting documentation data (extract-all.sh, analyze-docs.sh), deploying to docs.typo3.org + (webhook setup, publish documentation), or working with TYPO3 documentation guidelines. + + Covers: RST syntax, TYPO3-specific directives, documentation extraction/analysis, local Docker rendering, + validation procedures, webhook setup (gh CLI + manual), and TYPO3 Intercept deployment. Ensures documentation + meets modern TYPO3 13.x quality standards with card-grid navigation and renders correctly on docs.typo3.org. +license: Complete terms in LICENSE.txt +--- + +# TYPO3 Documentation + +## When to Use This Skill + +Invoke this skill when working with TYPO3 extension documentation: + +**File Patterns:** +- Editing `Documentation/**/*.rst` files +- Creating new RST files in Documentation/ directory +- Updating `Documentation/guides.xml` (modern PHP-based rendering) +- Updating `Documentation/Settings.cfg` (legacy Sphinx rendering - migrate to guides.xml) +- Editing `README.md` (requires syncing with Documentation/) + +**Keywords/Commands:** +- Creating: "create Documentation/", "generate documentation", "new docs" +- Using TYPO3 directives: `confval`, `versionadded`, `versionchanged`, `php:method`, `card-grid` +- Running: `ddev docs`, `scripts/validate_docs.sh`, `scripts/render_docs.sh` +- Extraction: `scripts/extract-all.sh`, `scripts/analyze-docs.sh` +- Deployment: "setup webhook", "deploy docs", "publish to docs.typo3.org", "docs.typo3.org" +- Mentions of: "TYPO3 documentation standards", "card-grid navigation", "confval directive" + +**Tasks:** +- Creating new TYPO3 extension documentation +- Extracting documentation data from code and configs +- Analyzing documentation coverage and identifying gaps +- Adding configuration documentation with confval directives +- Documenting version-specific changes (new features, behavior changes, deprecations) +- Creating visual navigation with card-grid layouts +- Documenting PHP APIs with php:method directives +- Validating RST syntax and cross-references +- Rendering documentation locally for verification +- Troubleshooting broken cross-references or rendering warnings +- Following TYPO3 documentation best practices + +## Workflow + +**Before editing Documentation/*.rst files or README.md:** +1. Invoke this skill if not already active +2. Optional: Run `scripts/extract-all.sh` and `scripts/analyze-docs.sh` for gap analysis (see `references/typo3-extension-architecture.md` for extraction priorities) +3. Review the workflow decision tree below +4. Use appropriate TYPO3 directives (not plain text equivalents) +5. Validate: `scripts/validate_docs.sh` or `ddev docs` +6. Check rendered output for warnings +7. **Verify synchronization:** If editing README.md, update Documentation/ accordingly (and vice versa) +8. Commit both README.md and Documentation/ together in atomic commits + +**Common Mistakes to Avoid:** +- ❌ Writing "Since v13.0.0" instead of `.. versionadded:: 13.0.0` +- ❌ Using card-grid without `stretched-link` class +- ❌ Skipping local rendering before committing +- ❌ Creating markdown files in Documentation/ (RST only) +- ❌ Missing `:type:`, `:Default:`, or `:Path:` in confval directives +- ❌ Using external links for internal documentation (use `:ref:` instead) +- ❌ **Updating README.md without updating Documentation/** (or vice versa) +- ❌ Using Title Case headlines instead of sentence case ("API Endpoints" → "API endpoints") +- ❌ Missing permalink anchors (`.. _section-label:`) before section headings +- ❌ List items without ending punctuation (periods) +- ❌ PHP code examples failing CGL checks (run `make fix-cgl`) + +## Documentation Synchronization + +**Critical Rule:** README.md and Documentation/ must stay synchronized. + +**When to sync:** +- Installation instructions changed → Update both README.md and Documentation/Introduction/Index.rst +- Feature descriptions changed → Update both README.md and Documentation/Index.rst +- Configuration examples changed → Update both README.md and Documentation/Integration/ +- Button names or UI elements mentioned → Verify consistency across all docs + +**Synchronization checklist:** +1. ✅ Installation steps match between README.md and Documentation/Introduction/ +2. ✅ Feature descriptions consistent between README.md and Documentation/Index.rst +3. ✅ Code examples identical (button names, configuration, TypoScript) +4. ✅ Version numbers consistent (README.md badges match Documentation/guides.xml or Settings.cfg) +5. ✅ Links to external resources point to same destinations + +**Example from real bug:** +```markdown +# README.md (WRONG) +toolbar: [typo3image] # Wrong button name + +# Documentation/Integration/RTE-Setup.rst (WRONG) +toolbar: [typo3image] # Wrong button name + +# Actual JavaScript code (CORRECT) +editor.ui.componentFactory.add('insertimage', ...) # Correct button name +``` + +**Fix approach:** +1. Find source of truth (usually the actual code) +2. Update README.md with correct information +3. Update all Documentation/*.rst files with same information +4. Commit both in same atomic commit + +## Documentation Structure + +### Three-Tier Documentation System + +TYPO3 extensions use a three-tier documentation structure: + +**1. Documentation/ (RST Format - Official Published)** +- Official TYPO3 documentation in reStructuredText format +- Published at docs.typo3.org +- Built automatically by TYPO3 Intercept +- Versioned and searchable across all TYPO3 docs +- **This is where to work when using this skill** + +**2. claudedocs/ (Markdown - AI Session Context)** +- Temporary session documentation (gitignored) +- Comprehensive project knowledge for AI agents +- Never committed to version control +- **Not relevant for this skill** + +**3. Root Documentation (Project Essentials)** +- README.md, CONTRIBUTING.md, SECURITY.md +- Project overview and guidelines +- **Not relevant for this skill** + +### Standard Documentation/ Structure + +``` +Documentation/ +├── Index.rst # Main entry point (required) +├── guides.xml # Documentation metadata (required - modern PHP-based rendering) +├── Settings.cfg # LEGACY - migrate to guides.xml (Sphinx-based, deprecated) +├── Introduction/ # Getting started content +├── Integration/ # Configuration guides +├── CKEditor/ # Feature-specific docs +├── Troubleshooting/ # Problem solving +├── Security/ # Security documentation +└── API/ # PHP API reference +``` + +## Documentation Extraction and Analysis + +### When to Use Extraction + +Use extraction tools when: + +- **Starting documentation for existing extension** - Extract data from code and configs +- **Auditing documentation coverage** - Identify undocumented APIs and configurations +- **Updating after code changes** - Find documentation gaps for new features +- **Ensuring consistency** - Verify docs match current code/config defaults + +### Extraction Workflow + +``` +1. Extract → 2. Analyze → 3. Generate (optional) → 4. Complete → 5. Validate +``` + +**1. Extract Data from All Sources** + +Run extraction to gather documentation data: + +```bash +scripts/extract-all.sh # Core extraction only +scripts/extract-all.sh --build # Include build configs +scripts/extract-all.sh --repo # Include GitHub/GitLab data +scripts/extract-all.sh --all # Extract everything +``` + +Extracted data saved to: `.claude/docs-extraction/data/*.json` + +**Sources:** +- PHP code (Classes/**/*.php) → php_apis.json +- Extension configs (ext_emconf.php, ext_conf_template.txt) → extension_meta.json, config_options.json +- Composer dependencies → dependencies.json +- Project files (README.md, CHANGELOG.md) → project_files.json +- Build configs (optional: .github/workflows, phpunit.xml) → build_configs.json +- Repository metadata (optional: GitHub/GitLab API) → repo_metadata.json + +**2. Analyze Documentation Coverage** + +Compare extracted data with existing Documentation/ using **feature-based coverage analysis** (see `references/documentation-coverage-analysis.md` for detailed methodology): + +```bash +scripts/analyze-docs.sh +``` + +Generates: `Documentation/ANALYSIS.md` with: +- **Summary**: Coverage statistics (X/Y classes documented, etc.) +- **Feature Coverage**: User-facing vs developer features documented +- **Extension Scope Assessment**: Small/medium/large classification +- **Missing Documentation**: Undocumented classes, configs, methods +- **Outdated Documentation**: Config defaults that don't match code +- **Recommendations**: Scope-appropriate prioritized action items + +**IMPORTANT**: Documentation excellence is measured by **feature coverage quality**, not static file count thresholds. A focused extension with 22 RST files covering 100% of user features is EXCELLENT, while a large CMS extension with 150+ files missing critical feature documentation is INSUFFICIENT. Always assess coverage relative to extension scope and actual features. + +**3. Review Analysis Report** + +Open and review `Documentation/ANALYSIS.md`: + +- Identify Priority 1 items (missing core documentation) +- Check Priority 2 items (outdated content) +- Plan documentation updates + +**4. Create Missing Documentation** + +For each missing item in ANALYSIS.md: + +**Classes/APIs:** +```bash +# Manually create based on php_apis.json data +# Location: Documentation/API/ClassName.rst +# Use php:class and php:method directives +``` + +**Configuration Options:** +```bash +# Add to existing or new configuration RST +# Location: Documentation/Integration/Configuration.rst +# Use confval directive with extracted data +``` + +**Extension Metadata:** +```bash +# Update Documentation/Index.rst +# Update Documentation/Settings.cfg +# Verify version numbers match ext_emconf.php +``` + +**5. Validate and Re-analyze** + +After updates: + +```bash +scripts/validate_docs.sh # Check RST syntax +scripts/render_docs.sh # Verify rendering +scripts/analyze-docs.sh # Re-check coverage +``` + +### Extraction Best Practices + +**DO:** +- Run extraction before starting documentation work +- Review ANALYSIS.md for systematic gap identification +- Use extracted data as templates (copy descriptions, defaults) +- Keep extraction data in .claude/ directory (gitignored) +- Re-run analyze-docs.sh after updates to track progress + +**DON'T:** +- Commit extraction data to version control +- Blindly copy extracted data without adding examples +- Skip the analysis step - it provides valuable insights +- Ignore security warnings in extracted config options +- Auto-generate docs without human review + +### Example: Documenting Undocumented Config Option + +**ANALYSIS.md reports:** +```markdown +### fetchExternalImages (ext_conf_template.txt) +- Type: boolean +- Default: true +- Security Warning: Enabling this setting fetches arbitrary URLs from the internet. +- Suggested Location: Integration/Configuration.rst +``` + +**Action:** + +1. Open `Documentation/Integration/Configuration.rst` +2. Add confval directive using extracted data: + +```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. + + .. warning:: + Enabling this setting fetches arbitrary URLs from the internet. + + Example + ------- + + Disable for security-sensitive installations: + + .. code-block:: php + :caption: ext_localconf.php + + $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image']['fetchExternalImages'] = false; +``` + +3. Re-run `scripts/analyze-docs.sh` to verify + +For complete extraction patterns and examples, see: `references/extraction-patterns.md` + +## Workflow Decision Tree + +**1. New Documentation?** +- Yes → Create Index.rst with card-grid navigation +- No → Go to step 2 + +**2. Adding Configuration?** +- Yes → Use confval directive (see "Configuration Documentation") +- No → Go to step 3 + +**3. Version-Specific Feature?** +- Yes → Use versionadded/versionchanged (see "Version Documentation") +- No → Go to step 4 + +**4. PHP API Documentation?** +- Yes → Use php:method directive (see "PHP API Documentation") +- No → Go to step 5 + +**5. Visual Navigation?** +- Yes → Use card-grid with stretched-link (see "Card Grid Navigation") +- No → Go to step 6 + +**6. Cross-References?** +- Yes → Use :ref: labels (see "Cross-References") +- No → Write standard RST content (see references/rst-syntax.md) + +**7. Setup Documentation Context (First Time)** +- Add AGENTS.md to Documentation/ folder +- Run scripts/add-agents-md.sh (creates context for AI assistants) + +**8. Always: Validate and Render** +- Run scripts/validate_docs.sh +- Run scripts/render_docs.sh +- Check for warnings and broken references + +## Modern TYPO3 13.x Standards + +### Default Patterns for New Documentation + +When creating new TYPO3 extension documentation, use these MODERN defaults: + +**1. Card-Grid Navigation (DEFAULT for Index.rst)** + +Always use card-grid instead of plain toctree lists: + +```rst +.. toctree:: + :hidden: + :maxdepth: 2 + + Introduction/Index + Installation/Index + Configuration/Index + +.. card-grid:: + :columns: 1 + :columns-md: 2 + :gap: 4 + :card-height: 100 + + .. card:: 📘 Introduction + + Learn what the extension does and key features. + + .. card-footer:: :ref:`Read more ` + :button-style: btn btn-primary stretched-link +``` + +**2. confval Directives (MANDATORY for Configuration)** + +Always use confval directive, never plain text: + +```rst +✅ Correct: +.. confval:: settingName + :type: boolean + :Default: true + :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['settingName'] + +❌ Wrong: +settingName +~~~~~~~~~~~ +Type: boolean +Default: true +``` + +**3. guides.xml (PREFERRED - Modern PHP-Based Rendering)** + +**ALWAYS use guides.xml for new extensions!** + +- guides.xml is the **modern standard** for TYPO3 documentation (PHP-based rendering) +- Settings.cfg is **LEGACY** (Sphinx-based) and being phased out +- guides.xml provides better GitHub integration, cross-extension interlinking, and maintainability +- For existing extensions with Settings.cfg: **migrate to guides.xml** + +**Minimum guides.xml Structure:** + +```xml + + + + + + + + + + +``` + +**Migration from Settings.cfg to guides.xml:** + +1. Create guides.xml with above structure +2. Map Settings.cfg values: + - `[general] project` → `` + - `[general] version` → `` + - `[general] copyright` → `` + - `[html_theme_options] github_repository` → `edit-on-github=""` + - `[html_theme_options] github_branch` → `edit-on-github-branch=""` + - `[html_theme_options] project_*` → corresponding `project-*` attributes + - `[intersphinx_mapping]` → `` elements +3. Test build: `ddev docs` +4. Delete Settings.cfg after successful migration + +**4. Missing Images Handling** + +When documentation references non-existent images: + +**Best Practice:** Remove figure directives, add descriptive content: + +```rst +❌ Wrong (causes rendering errors): +.. figure:: /Images/screenshot.png + :alt: Screenshot description + +✅ Correct: +.. note:: + Screenshots will be added in a future update. + +The backend module provides: +- Feature 1: Description +- Feature 2: Description + +.. todo:: + Add screenshot showing the backend module interface +``` + +**Alternative:** Create `.gitkeep` in `Documentation/Images/` for future additions + +### Common Pitfalls and Fixes + +**Pitfall 1: Plain Toctree Instead of Card-Grid** +- ❌ Creates plain bulleted list (outdated) +- ✅ Use card-grid with emoji icons (modern standard) + +**Pitfall 2: Plain Text Configuration** +- ❌ Uses "Type:", "Default:" format +- ✅ Use confval directive with `:type:`, `:Default:`, `:Path:` + +**Pitfall 3: Using Settings.cfg Instead of guides.xml** +- ❌ Uses Settings.cfg → legacy Sphinx-based rendering +- ✅ Use guides.xml for modern PHP-based rendering (preferred) + +**Pitfall 4: Image References Without Images** +- ❌ Leaves broken figure directives +- ✅ Remove directives, add descriptive content + todo notes + +**Pitfall 5: Missing stretched-link in Card Footer** +- ❌ Only button text is clickable +- ✅ Add `stretched-link` class for full card clickability + +## Configuration Documentation + +To document configuration values, use the `confval` directive: + +```rst +.. confval:: settingName + + :type: boolean + :Default: true + :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['setting'] + + Description of the configuration value. Explain what it does, + when to use it, and any important considerations. +``` + +**Required Fields:** +- `:type:` - Data type (boolean, string, integer, array, object) +- `:Default:` - Default value (capitalize 'Default') +- `:Path:` - Full path in TYPO3 configuration + +**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. +``` + +For detailed confval syntax and more examples, see: `references/typo3-directives.md` + +## Version Documentation + +To document version-specific changes, use version directives: + +**New Feature:** +```rst +.. versionadded:: 13.0.0 + The CKEditor plugin now requires ``StyleUtils`` and ``GeneralHtmlSupport`` + dependencies for style functionality. +``` + +**Changed Behavior:** +```rst +.. versionchanged:: 13.1.0 + Image processing now uses TYPO3's native image processing service. +``` + +**Deprecated Feature:** +```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 content they describe. + +## PHP API Documentation + +To document PHP classes and methods, use the PHP domain directives: + +**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 + :returntype: \\Psr\\Http\\Message\\ResponseInterface + :throws \\RuntimeException: When file is not found +``` + +**Return Type Strategy (Hybrid Rule):** + +Use context-appropriate return type documentation based on complexity: + +1. **Simple types (string, int, bool, array):** Include in signature only + ```rst + .. php:method:: isEnabled(): bool + + Checks if the configuration is valid. + ``` + +2. **TYPO3 types with clear meaning:** Include in signature + `:returntype:` for FQN + ```rst + .. php:method:: getFile(int $uid): File|null + + Retrieves file by UID. + + :returntype: ``\\TYPO3\\CMS\\Core\\Resource\\File|null`` + ``` + +3. **Complex union types (>2 types or long FQNs):** Use `:returntype:` field only + ```rst + .. php:method:: processImage(File $file, array $options) + + Processes image with multiple return possibilities. + + :returns: Processed file, original file if no processing needed, or null on error + :returntype: ``\\TYPO3\\CMS\\Core\\Resource\\ProcessedFile|\\TYPO3\\CMS\\Core\\Resource\\File|null`` + ``` + +**Rationale:** Balance readability (signature for quick scan) with precision (field for complex types) + +**Class:** +```rst +.. php:class:: SelectImageController + + Main controller for image selection wizard. + + Extends: ``TYPO3\\CMS\\Backend\\Controller\\ElementBrowserController`` +``` + +For complete PHP domain reference, see: `references/typo3-directives.md` + +## Card Grid Navigation + +To create visual navigation, use card-grid layouts with stretched links: + +```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 ` + :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 ` + :button-style: btn btn-secondary stretched-link +``` + +**Critical Elements:** +- UTF-8 emoji icons in card titles (📘, 🔧, 🎨, 🔍, ⚡, 🛡️, etc.) +- `stretched-link` class in card-footer for full card clickability +- `:ref:` cross-references in card-footer + +For complete card-grid reference, see: `references/typo3-directives.md` + +## Code Snippets with literalinclude + +For PHP scripts, configuration files, or other code examples, prefer `literalinclude` over inline code blocks: + +**Benefits:** +- DRY: Single source of truth for code +- Testable: Referenced file can be syntax-checked/executed +- GitHub link: Rendered docs include "Edit on GitHub" link +- Maintainable: Update code in one place + +**Basic Usage:** +```rst +.. literalinclude:: _codesnippets/example.php + :caption: example.php + :language: php +``` + +**With Line Selection:** +```rst +.. literalinclude:: _codesnippets/example.php + :caption: Relevant excerpt + :language: php + :lines: 10-25 +``` + +**With Highlighting:** +```rst +.. literalinclude:: _codesnippets/example.php + :caption: example.php + :language: php + :emphasize-lines: 5,10-12 +``` + +**Directory Structure:** +``` +Documentation/ +├── Section/ +│ ├── Index.rst +│ └── _codesnippets/ +│ ├── example.php +│ └── config.yaml +``` + +**When to Use:** +- ✅ Scripts longer than ~20 lines +- ✅ Code that should be executable/testable +- ✅ Examples referenced from multiple places +- ❌ Short inline examples (use code-block) +- ❌ Pseudo-code or partial snippets + +## PHP Code CGL Compliance + +PHP code examples in TYPO3 documentation **MUST** pass CGL (Coding Guidelines) checks. + +**Why:** +- TYPO3 documentation builds enforce coding standards +- Non-compliant code causes build warnings/failures +- Consistent formatting improves readability + +**Validation:** +```bash +# Run CGL check locally before committing +make fix-cgl + +# Or using Docker +ddev exec make fix-cgl +``` + +**Common CGL Issues:** +- Missing/incorrect spacing around operators +- Improper array formatting +- Wrong indentation (4 spaces, not tabs) +- Missing blank lines between functions +- Line length exceeding limits + +**Example Fix:** +```php +// ❌ Before (CGL violation) +function getItems($id){return $this->items[$id];} + +// ✅ After (CGL compliant) +function getItems(int $id): array +{ + return $this->items[$id]; +} +``` + +**Best Practice:** +1. Write code examples following PSR-12 and TYPO3 CGL +2. Run `make fix-cgl` before committing +3. Fix any reported issues before pushing +4. If build fails on CI, check CGL compliance first + +## Cross-References + +To create internal links, use labels and `:ref:`: + +**Create Label:** +```rst +.. _my-section-label: + +Section Title +============= +``` + +**Reference Label:** +```rst +Link to :ref:`my-section-label` +Link with custom text: :ref:`Custom Text ` +``` + +**TYPO3 Core Documentation:** +```rst +:ref:`t3tsref:start` - TypoScript Reference +:ref:`t3coreapi:fal` - File Abstraction Layer +:ref:`t3tsconfig:pagetsconfig` - Page TSConfig +``` + +## Validation and Rendering + +### Validate Documentation + +Use the validation script to check RST syntax and common issues: + +```bash +scripts/validate_docs.sh /path/to/project +``` + +**Checks:** +- RST file existence and count +- Settings.cfg presence +- Index.rst presence +- RST syntax validation +- UTF-8 encoding +- Trailing whitespace +- Common reference issues + +### Render Documentation Locally + +Use the rendering script to generate HTML output: + +```bash +scripts/render_docs.sh /path/to/project +``` + +**Output:** `Documentation-GENERATED-temp/Index.html` + +**View:** +```bash +open Documentation-GENERATED-temp/Index.html +# or +xdg-open Documentation-GENERATED-temp/Index.html +``` + +**Always render locally before committing to verify:** +- No rendering warnings +- No broken cross-references +- Proper formatting +- Card grids display correctly +- Code blocks render properly + +## Common Tasks + +### Add New Page + +1. Create `Documentation/Section/NewPage.rst` +2. Add to parent `Index.rst` toctree: + ```rst + .. toctree:: + :maxdepth: 2 + + Introduction/Index + Section/NewPage + ``` +3. Add label at top: `.. _section-newpage:` +4. Validate: `scripts/validate_docs.sh` +5. Render: `scripts/render_docs.sh` +6. Commit changes + +### Update Configuration + +1. Find relevant RST file in `Integration/` +2. Add or update `.. confval::` directive +3. Include `:type:`, `:Default:`, `:Path:` +4. Provide clear description +5. Validate and render + +### Document Version Changes + +1. Add `.. versionadded::` or `.. versionchanged::` +2. Include version number +3. Describe what changed and why +4. Place near relevant content +5. Validate and render + +### Fix Cross-References + +1. Find broken reference in render warnings +2. Check if target label exists +3. Update reference or create missing label +4. Re-render to verify fix + +## Pre-Commit Validation + +Before committing documentation changes, perform these quality checks in order: + +1. **Run validation**: Execute `scripts/validate_docs.sh` to check RST syntax, encoding, and structural issues +2. **Render locally**: Execute `scripts/render_docs.sh` and verify no rendering warnings appear +3. **Check cross-references**: Confirm all `:ref:` labels resolve correctly in rendered output +4. **Verify directives**: Ensure all `confval` directives include `:type:`, `:Default:`, and `:Path:` fields +5. **Confirm version markers**: Add `versionadded`/`versionchanged` directives for new features or changed behavior +6. **Test card grids**: Verify card-footer buttons include `stretched-link` class for full card clickability +7. **Check visual elements**: Confirm card titles use UTF-8 emoji icons (📘 🔧 🎨 etc.) +8. **Validate code blocks**: Ensure all code blocks specify language (`:caption:` optional) +9. **Review heading structure**: Verify proper hierarchy (= for title, - for sections, ~ for subsections) +10. **Check PHP signatures**: Confirm method signatures include return types (either in signature or `:returntype:` field) +11. **Verify sentence case**: Headlines must use sentence case, NOT title case ("API endpoints" not "API Endpoints") +12. **Check permalink anchors**: Every section must have a `.. _label:` anchor for deep linking +13. **Verify list punctuation**: All list items should end with periods +14. **Run CGL checks**: Execute `make fix-cgl` for PHP code examples in `_codesnippets/` directories + +Additionally, verify documentation coverage meets standards: +- Public APIs have corresponding `php:method` or `php:class` documentation +- Configuration options documented with `confval` directives +- Features include usage examples and integration guides +- Common issues addressed in Troubleshooting section +- Security considerations noted for sensitive features + +## TYPO3 Intercept Deployment + +TYPO3 Intercept provides automatic documentation rendering and publishing. Properly configured repositories automatically build and publish documentation to docs.typo3.org. + +### Prerequisites + +Before enabling automatic deployment: + +1. **Extension in TER**: Extension must be registered in TYPO3 Extension Repository with same key as `composer.json` +2. **Git Repository Referenced**: Repository URL must be listed on TER detail page +3. **Documentation Structure**: Must include `Index.rst`, `Settings.cfg`, and valid RST files + +### Webhook Registration + +**GitHub Setup:** +1. Repository Settings → Webhooks → Add webhook +2. Payload URL: `https://docs-hook.typo3.org` +3. Content type: `application/json` +4. Enable SSL verification +5. Events: "Just the push event" +6. Mark as Active + +**GitLab Setup:** +1. Project Settings → Webhooks +2. URL: `https://docs-hook.typo3.org` +3. Triggers: Push events + Tag push events +4. Enable SSL verification + +### Automated Webhook Setup (GitHub CLI) + +**Faster alternative for GitHub repositories:** + +If you have `gh` CLI installed, automate webhook creation: + +```bash +# Create webhook +gh api repos/{owner}/{repo}/hooks \ + --method POST \ + --field name=web \ + --field "config[url]=https://docs-hook.typo3.org" \ + --field "config[content_type]=json" \ + --field "config[insecure_ssl]=0" \ + --raw-field "events[]=push" \ + --field active=true + +# Trigger test delivery +gh api repos/{owner}/{repo}/hooks/{hook_id}/tests --method POST + +# Verify delivery status +gh api repos/{owner}/{repo}/hooks/{hook_id}/deliveries \ + --jq '.[] | {id: .id, status: .status, status_code: .status_code, delivered_at: .delivered_at}' +``` + +**Expected response:** Status 200 or 204 indicates successful webhook delivery. + +**Check webhook ID:** +```bash +gh api repos/{owner}/{repo}/hooks --jq '.[] | {id: .id, url: .config.url, events: .events}' +``` + +### First-Time Approval + +First webhook trigger requires manual approval by TYPO3 Documentation Team: +- Automatic hold on first build +- Team verifies TER registration and repository reference +- Typical approval time: 1-3 business days +- Future builds are automatic after approval + +### Verification + +**Check Webhook Delivery:** +- GitHub: Settings → Webhooks → Recent Deliveries (expect `200` response) +- GitLab: Settings → Webhooks → Recent events (verify success) + +**Check Build Status:** +- Dashboard: https://intercept.typo3.com/admin/docs/deployments +- Filter by extension package name +- Monitor build progress and success status + +**Published Documentation:** +``` +https://docs.typo3.org/p/{vendor}/{extension}/main/en-us/ +https://docs.typo3.org/p/{vendor}/{extension}/{version}/en-us/ +``` + +### Automatic Triggers + +Builds triggered by: +- Git push to main/master +- Version tags (e.g., `2.1.0`) +- Branch pushes (for multi-version docs) + +### Manual Rebuild + +If needed: +1. Visit https://intercept.typo3.com/admin/docs/deployments +2. Find your extension +3. Click Redeploy button + +### Build Process + +1. Webhook received from Git host +2. Build job queued +3. Repository cloned at specific commit/tag +4. Documentation rendered using `render-guides` +5. HTML published to docs.typo3.org +6. Content indexed for search + +**Typical build time:** 2-5 minutes + +### Troubleshooting + +**Build Failing:** +- Validate RST syntax locally: `scripts/validate_docs.sh` +- Render locally: `scripts/render_docs.sh` +- Check for broken cross-references +- Verify UTF-8 encoding + +**Common Rendering Errors:** + +1. **guides.xml Extension Class Path Error** + ``` + Extension "\T3Docs\GuidesExtension\..." does not exist + ``` + **Fix:** Ensure correct `class` attribute in guides.xml: + ```xml + /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 diff --git a/references/extraction-patterns.md b/references/extraction-patterns.md new file mode 100644 index 0000000..a282e5e --- /dev/null +++ b/references/extraction-patterns.md @@ -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 + '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 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/ diff --git a/references/intercept-deployment.md b/references/intercept-deployment.md new file mode 100644 index 0000000..3addf9e --- /dev/null +++ b/references/intercept-deployment.md @@ -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) diff --git a/references/rst-syntax.md b/references/rst-syntax.md new file mode 100644 index 0000000..aef8fd9 --- /dev/null +++ b/references/rst-syntax.md @@ -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 + + `__ +``` + +**Internal Cross-References:** +```rst +.. _my-label: + +Section Title +============= + +Link to :ref:`my-label` +Link with custom text: :ref:`Custom Text ` +``` + +**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/ diff --git a/references/typo3-directives.md b/references/typo3-directives.md new file mode 100644 index 0000000..180e6f9 --- /dev/null +++ b/references/typo3-directives.md @@ -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 + + + +``` + +**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 ` + :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 ` + :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/ diff --git a/references/typo3-extension-architecture.md b/references/typo3-extension-architecture.md new file mode 100644 index 0000000..0af9718 --- /dev/null +++ b/references/typo3-extension-architecture.md @@ -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:** `.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:** `.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/ diff --git a/scripts/add-agents-md.sh b/scripts/add-agents-md.sh new file mode 100755 index 0000000..7771b22 --- /dev/null +++ b/scripts/add-agents-md.sh @@ -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" diff --git a/scripts/analyze-docs.sh b/scripts/analyze-docs.sh new file mode 100755 index 0000000..f8d2f5b --- /dev/null +++ b/scripts/analyze-docs.sh @@ -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 +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}" <> "${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}" </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}" <> "${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}" <> "${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 diff --git a/scripts/extract-all.sh b/scripts/extract-all.sh new file mode 100755 index 0000000..5a93e6d --- /dev/null +++ b/scripts/extract-all.sh @@ -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 diff --git a/scripts/extract-build-configs.sh b/scripts/extract-build-configs.sh new file mode 100755 index 0000000..de3dda9 --- /dev/null +++ b/scripts/extract-build-configs.sh @@ -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}" diff --git a/scripts/extract-composer.sh b/scripts/extract-composer.sh new file mode 100755 index 0000000..efe4311 --- /dev/null +++ b/scripts/extract-composer.sh @@ -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}" diff --git a/scripts/extract-extension-config.sh b/scripts/extract-extension-config.sh new file mode 100755 index 0000000..bfd0ec4 --- /dev/null +++ b/scripts/extract-extension-config.sh @@ -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 diff --git a/scripts/extract-php.sh b/scripts/extract-php.sh new file mode 100755 index 0000000..1d582e2 --- /dev/null +++ b/scripts/extract-php.sh @@ -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 diff --git a/scripts/extract-project-files.sh b/scripts/extract-project-files.sh new file mode 100755 index 0000000..7fc2110 --- /dev/null +++ b/scripts/extract-project-files.sh @@ -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}" diff --git a/scripts/extract-repo-metadata.sh b/scripts/extract-repo-metadata.sh new file mode 100755 index 0000000..42a9d64 --- /dev/null +++ b/scripts/extract-repo-metadata.sh @@ -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" diff --git a/scripts/render_docs.sh b/scripts/render_docs.sh new file mode 100755 index 0000000..7009dc2 --- /dev/null +++ b/scripts/render_docs.sh @@ -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 diff --git a/scripts/validate_docs.sh b/scripts/validate_docs.sh new file mode 100755 index 0000000..67ac469 --- /dev/null +++ b/scripts/validate_docs.sh @@ -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" diff --git a/templates/AGENTS.md b/templates/AGENTS.md new file mode 100644 index 0000000..ddbfcdc --- /dev/null +++ b/templates/AGENTS.md @@ -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 + + + + + + +**Target Audience:** + +**Main Topics:** + +**Not Covered:** + +## Documentation Framework + +- **Format**: reStructuredText (RST) +- **Build System**: TYPO3 Documentation rendering tools +- **Published At**: https://docs.typo3.org/p/[vendor]/[extension]/main/en-us/ +- **Automated Build**: TYPO3 Intercept webhook deployment + +## File Structure + +### Required Files + +- `Index.rst` - Main documentation entry point +- `Settings.cfg` - Documentation metadata and configuration + +### Common Sections + +- `Introduction/` - Getting started, features overview +- `Installation/` - Installation and upgrade guides +- `Configuration/` - TypoScript, extension configuration +- `Integration/` - Integration with other systems +- `Editor/` - User guide for content editors +- `Developer/` - Developer documentation +- `API/` - PHP API reference documentation +- `Troubleshooting/` - Common issues and solutions + +## TYPO3-Specific Directives + +### Configuration Documentation + +Use `confval` for configuration options: + +```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 ` + + How to install and configure the extension. + + .. card:: :ref:`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 ` +``` + +### 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 + +