docs: documentation overhaul — restructure, branding, ADRs, cache fix - #110
Conversation
…art page - Add new Administration/Index.rst with step-by-step guides for managing providers, models, configurations, tasks, and AI wizards including screenshots of every backend screen - Redesign start page (Index.rst) with audience-grouped card sections (Getting started / For administrators / For developers) and emoji icons - Trim Configuration/Index.rst to pure field reference (was 716 lines, now ~400) — admin walkthrough content moved to Administration - Refresh all 8 backend screenshots with current TYPO3 v14 UI - Update API reference with missing methods (analyzeImageFull, pairwiseSimilarities, VisionResponse class, thinking support) - Fix test counts in Testing guide (unit 384→2735, functional 39→285) - Add OpenRouter embeddings capability to README and Introduction - Fix broken configuration-wizards cross-reference Signed-off-by: Sebastian Mendel <sebastian.mendel@netresearch.de> Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
github-actions
Bot
added
the
documentation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the documentation by restructuring it to better serve different user audiences, particularly administrators. It introduces a dedicated administration guide with detailed, step-by-step instructions and visual aids, while streamlining existing reference material. The changes aim to make the documentation more accessible and user-friendly for both new and experienced users managing AI features within the TYPO3 environment. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly restructures and improves the documentation by adding a dedicated administration guide, redesigning the start page for different audiences, and refactoring existing content. The changes make the documentation more user-friendly and easier to navigate. My review focuses on enhancing consistency and clarity in the new content. I've provided suggestions to standardize API signatures in the documentation, unify example model names, and ensure code snippets are complete and well-formatted.
There was a problem hiding this comment.
Pull request overview
This PR refreshes and restructures the extension documentation to better separate administrator guidance from configuration/API reference, while updating provider capability listings and API docs for recently added/expanded features.
Changes:
- Added a new Administration guide and reorganized the main docs landing page into admin/developer-focused entry points.
- Updated provider capability documentation (notably OpenRouter) and expanded API reference coverage (EmbeddingService pairwise similarities, VisionService batch/options usage, CompletionResponse thinking/metadata, VisionResponse).
- Updated testing documentation structure/labels and refreshed screenshots (new providers list image).
Reviewed changes
Copilot reviewed 7 out of 15 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates the supported provider capabilities table (OpenRouter now includes embeddings). |
| Documentation/Testing/Index.rst | Updates test-suite counts and renames “Property tests” section to “Fuzzy tests”. |
| Documentation/Introduction/Index.rst | Updates provider capability wording and fixes wizard cross-reference target. |
| Documentation/Index.rst | Restructures the documentation landing page and adds an intro screenshot section. |
| Documentation/Images/backend-providers.png | Adds/updates the providers list screenshot referenced by docs. |
| Documentation/Configuration/Index.rst | Refactors into a “Configuration reference” and moves step-by-step guidance out to Administration docs; updates formatting and snippets. |
| Documentation/Api/Index.rst | Adds/extends API reference entries (EmbeddingService/VisionService/CompletionResponse/VisionResponse). |
| Documentation/Administration/Index.rst | New admin-focused guide covering backend module workflows and AI wizards. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Split 5 monolithic pages into 27 focused sub-pages: - Api (758→10 files): per-service + response objects + options + exceptions - Testing (559→5 files): unit, functional, E2E, CI config - Administration (463→6 files): providers, models, configs, tasks, wizards - Configuration (456→6 files): field references per entity + settings - Developer (462→4 files): streaming, tool calling, custom providers Total rendered pages: 27 → 60. No content deleted, only reorganized. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
- ADR-014: AI-powered wizard system (setup, config, task wizards) - ADR-015: Type-safe domain models via PHP 8.1+ enums & value objects - ADR-016: Thinking/reasoning block extraction from LLM responses - ADR-017: SafeCastTrait for PHPStan level 10 compliance - ADR-018: Multi-provider model discovery with fallback catalogs - ADR-019: Internationalization strategy with locale-aware features - ADR-020: Backend output format rendering (plain/markdown/HTML) Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
- Teal SVG underline below main heading - [n] Netresearch footer card with brand identity - Emoji icons on all navigation cards - Documentation license: CC BY 4.0 - guides.xml: add project-issues, project-discussions, edit-on-github-directory; contact via GitHub Discussions Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Remove SimpleFileBackend from cache configuration so TYPO3 uses the instance's default cache backend. Redis/Valkey/Memcached now work transparently if configured by the admin. Also fix cache group: 'system' -> 'nrllm' to match documentation (cache:flush --group=nrllm). Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Reflect 20 ADRs, 60 rendered doc pages, cache backend change, branding assets, and complete guides.xml configuration. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
github-actions
Bot
added
tests
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
- Add screenshots: task execution form, provider test modal, configuration test modal, task list with 13 seeded tasks - Fix security docs: sodium_crypto_secretbox -> nr-vault envelope encryption (nr-llm delegates all encryption to nr-vault) - ADR index: card-grid layout grouped by category (foundation, TYPO3 integration, API design, modern architecture) Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 54 out of 67 changed files in this pull request and generated 15 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Previous screenshots were taken at ~780px viewport, cutting off sidebar, table columns, and modal backgrounds. Retaken at 1440x900 for full TYPO3 backend context. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
CybotTM
changed the title
- Fix invalid PHP in cache backend examples (split class names) - Restore TypoScript providers block in config reference - Add chatCompletion() context to sanitization/output examples - Fix logging code block to PSR-12 style - Update API signatures: VisionService, LlmServiceManager, TranslationService, ProviderInterface to match actual code - Fix ProviderFields: nr-vault instead of sodium, conditional required - Fix UnitTesting: remove --dev flag, use placeholder API key - Rewrite EndToEndTesting: actual E2E workflow test content - Fix AGENTS.md files: nr-vault refs, tag mismatch, directory tree Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 54 out of 67 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
- CompletionService: array $options -> ?ChatOptions $options = null - EmbeddingService: add ?EmbeddingOptions $options = null params - EndToEndTesting: fix runTests command, fix RST underline length Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
There was a problem hiding this comment.
Automated approval for solo maintainer project
This PR has passed all automated quality gates:
- ✅ Static analysis (PHPStan)
- ✅ Code style (PHP-CS-Fixer)
- ✅ Unit & functional tests
- ✅ Security scanning
- ✅ Dependency review
See SECURITY_CONTROLS.md for compensating controls documentation.
Summary
Complete documentation overhaul for nr-llm covering structure, branding, architecture decisions, and a cache backend fix.
sodium_crypto_secretboxto nr-vault envelope encryptionSimpleFileBackend, fixed groupsystem→nrllm. TYPO3 now uses instance default (Redis/Valkey/Memcached work transparently)Test plan
Build/Scripts/runTests.sh -s unit -p 8.4— all 2735 tests passvendor/bin/typo3 cache:flush --group=nrllm