documentation #3491 [Turbo] Restructure and standardize the documentation (seb-jean)

This PR was merged into the 3.x branch.

Discussion
----------

[Turbo] Restructure and standardize the documentation

| Q              | A
| -------------- | ---
| Bug fix?       | no
| New feature?   | no <!-- please update src/**/CHANGELOG.md files -->
| Deprecations?  | no <!-- if yes, also update UPGRADE-*.md and src/**/CHANGELOG.md -->
| Documentation? | yes <!-- required for new features, or documentation updates -->
| Issues         | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License        | MIT

Over the past few days, I took the time to thoroughly rework the Symfony UX Turbo documentation to improve its clarity, consistency and quality.

  Changes:

  - Unify all code examples around a single Task entity thread (controller, form, templates)
  - Split the monolithic index.rst into focused sub-pages (`custom-transport`, `multiple-submit-buttons`, `multiple-transports`, `resetting-form`, `testing`, `webpack-encore`)
  - Apply Symfony documentation standards
  - Add missing namespace, use statements and `#[Route]` attributes in PHP examples
  - Fix trailing commas in PHP arrays
  - Add "Minimal Frame Layout" section with ``@Turbo`/layouts/frame.html.twig`
  - Add "Custom Action" section for `<twig:Turbo:Stream>` and `TurboStreamResponse::action()`

Commits
-------

5257a90 [Turbo] Restructure and standardize the documentation

Author: Kocal

src/Turbo/README.md

@@ -12,7 +12,7 @@ or any other transports to broadcast DOM changes to all currently connected user
 You're in a hurry? Take a look at [the chat example](https://symfony.com/bundles/ux-turbo/current/index.html#chat-example)
 to discover the full potential of Symfony UX Turbo.
 
-Or watch the [Turbo Screencast on SymfonyCasts](https://symfonycasts.com/screencast/turbo).
+Or watch the [Symfony UX Turbo screencast series](https://symfonycasts.com/screencast/turbo).
 
 **This repository is a READ-ONLY sub-tree split**. See
 https://github.com/symfony/ux to create issues or submit pull requests.

src/Turbo/doc/custom-transport.rst

@@ -0,0 +1,55 @@
+How to Register a Custom Transport
+==================================
+
+If you prefer using another protocol than Mercure, you can create custom
+transports::
+
+    // src/Turbo/Broadcaster.php
+    namespace App\Turbo;
+
+    use Symfony\UX\Turbo\Attribute\Broadcast;
+    use Symfony\UX\Turbo\Broadcaster\BroadcasterInterface;
+
+    class Broadcaster implements BroadcasterInterface
+    {
+        public function broadcast(object $entity, string $action): void
+        {
+            // Called every time an object marked with #[Broadcast] changes
+            $attribute = (new \ReflectionClass($entity))
+                ->getAttributes(Broadcast::class)[0] ?? null;
+            // ...
+        }
+    }
+
+Then a stream source renderer::
+
+    // src/Turbo/MyStreamSourceRenderer.php
+    namespace App\Turbo;
+
+    use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;
+    use Symfony\UX\Turbo\StreamSourceRendererInterface;
+
+    #[AsTaggedItem(index: 'my-transport')]
+    class MyStreamSourceRenderer implements StreamSourceRendererInterface
+    {
+        public function render(string|object|array $topics, array $options = []): string
+        {
+            $url = 'https://my-transport.example.com/subscribe?topic='.$topics;
+            $private = $options['private'] ?? false;
+
+            return \sprintf(
+                '<my-custom-stream-source src="%s"%s></my-custom-stream-source>',
+                htmlspecialchars($url, \ENT_QUOTES | \ENT_SUBSTITUTE, 'UTF-8'),
+                $private ? ' private' : '',
+            );
+        }
+    }
+
+The broadcaster must be registered as a service tagged with
+``turbo.broadcaster`` and the stream source renderer must be tagged with
+``turbo.stream_source_renderer``. If you enabled `autoconfigure option`_
+(it's the case by default), these tags will be added automatically because
+these classes implement the ``BroadcasterInterface`` and
+``StreamSourceRendererInterface`` interfaces.
+
+.. _`autoconfigure option`: https://symfony.com/doc/current/service_container.html#the-autoconfigure-option