Documentation in template files (#6)

provides possibility to add documentation in templates with a twig-comment: {#TWIG_DOC ... TWIG_DOC#}

.gitignore

@@ -1,5 +1,7 @@
 /var/
 /vendor/
+/report/
 .phpunit.cache
+.phpunit.result.cache
 composer.lock
 .php-cs-fixer.cache

README.md

@@ -1,10 +1,20 @@
 ## Twic Doc Bundle
 
-Allows you to create an overview for your Twig Components, be it either UX-Components, UX-Live-Components or simple snippet templates.
+[![Image](docs/resources/images/qossmic.png)](https://qossmic.com) Brought to you by qossmic! 
 
-Components will be grouped in categories and optional sub-categories.
+1. [Installation](#installation)
+2. Configuration
+   1. [Bundle Configuration](docs/BundleConfiguration.md)
+   2. [Component Configuration](docs/ComponentConfiguration.md)
+3. [Routing](#routing)
+4. [Customization](#customizing-the-design)
+5. [Usage](docs/Usage.md)
+
+---
 
-The categories must be configured in the bundle-configuration, see below.
+Allows you to create an overview for your Twig Components, be it either [UX-Components](https://symfony.com/bundles/ux-twig-component/current/index.html), [UX-Live-Components](https://symfony.com/bundles/ux-live-component/current/index.html) or simple snippet templates.
+
+Components will be grouped in categories and optional sub-categories.
 
 ### Installation
 
@@ -38,110 +48,8 @@ twig_doc:
   # or for localized: prefix: /{_locale}/twig/doc/
 ```
 
-### Template
-
-To use your design in the documentation, you have to override the component template.
-
-Create a template in your project: templates/bundles/TwigDocBundle/component.html.twig
-
-```twig
-{% extends '@!TwigDoc/component.html.twig' %}
-
-{% block stylesheets %}
-    <link rel="stylesheet" href="{{ asset('css/your-styles.css') }}">
-{% endblock %}
-```
-
-#### Customizing the documentation
-
-If you want to customize the documentation, you can override the template.
-
-Create a template in your project: templates/bundles/TwigDocBundle/documentation.html.twig
-
-```twig
-{% extends '@!TwigDoc/documentation.html.twig' %}
-
-{% block stylesheets %}
-    <link rel="stylesheet" href="{{ asset('css/your-styles.css') }}">
-{% endblock %}
-```
-
-### Configuration
+### Customizing the design
 
-Create a config file: configs/packages/twig_doc.yaml
+To customize the design of the documentation, you can override any template of the bundle in your project.
 
-#### Configure categories
-
-```yaml
-twig_doc:
-  categories:
-    - name: Button
-      sub_categories:
-        - Action
-        - Submit
-    - name: Heading
-    - name: Notification
-      sub_categories:
-        - Alert
-        - Flash
-#... component config
-```
-
-#### Example for a Twig UX-Component
-
-```yaml
-twig_doc:
-  #... categories config
-  components:
-    - name: ActionButton # will render %kernel.project_dir%/templates/components/ActionButton.html.twig
-      title: Action Button
-      description: An Action button
-      category: Buttons
-      sub_category: Action
-      tags:
-        - buttons
-      parameters:
-        color: String
-        text: String
-        link: String
-      variations:
-        secondary:
-          color: secondary
-          text: Secondary Button
-          link: '#'
-        primary:
-          color: primary
-          text: Primary Button
-          link: '#'
-```
-The bundle will look for this component in the folder configured for the ux-twig-component bundle (default: %kernel.project_dir%/templates/components/COMPONENT_NAME.html.twig).
-
-#### Example for a non ux-twig-component
-
-The only difference is that non-ux components use another default-path and the naming is not specified.
-
-```yaml
-twig_doc:
-  #... categories config
-  components:
-    - name: snippets/alert # will render %kernel.project_dir%/templates/snippets/alert.html.twig
-      title: Alert
-      description: non twig-ux-component component
-      category: Notification
-      sub_category:
-        - Alert
-      tags:
-        - highlight
-        - nameIt
-      parameters:
-        type: String
-        msg: String
-      variations:
-        primary:
-          type: primary
-          msg: Primary Alert
-        danger:
-          type: danger
-          msg: Danger Alert
-```
-The bundle will look for this template in the twig template folder (default: %kernel.project_dir%/templates/COMPONENT_NAME.html.twig).
+See: [How to override any Part of a Bundle](https://symfony.com/doc/current/bundles/override.html)

composer.json

@@ -18,12 +18,14 @@
     "php": ">=8.2",
     "symfony/framework-bundle": "^6.4|^7.0",
     "symfony/validator": "^6.4|^7.0",
-    "symfony/twig-bundle": "^6.4|^7.0"
+    "symfony/twig-bundle": "^6.4|^7.0",
+    "symfony/yaml": "^6.4|^7.0"
   },
   "require-dev": {
     "phpunit/phpunit": "^10.5",
     "symfony/browser-kit": "^6.4|^7.0",
     "symfony/css-selector": "^6.4|^7.0",
+    "symfony/dom-crawler": "^6.4|^7.0",
     "friendsofphp/php-cs-fixer": "^3.51"
   }
 }

docs/BundleConfiguration.md

@@ -0,0 +1,68 @@
+## Configuring the bundle
+
+When you do not want to customize, you do not need any config file. 
+
+The bundle provides following defaults:
+
+```yaml
+twig_doc:
+  doc_identifier: TWIG_DOC
+  directories:
+    - '%twig.default_path%/components'
+  categories:
+    - name: Components
+```
+
+### Directories
+
+By default, the bundle looks for your components in this directory: `%twig.default_path%/components`
+
+You can provide additional directories in the config-file:
+
+```yaml
+twig_doc:
+    directories:
+      - '%twig.default_path%/snippets'
+      - '%kernel.project_dir%/resources/components'
+```
+
+### Documentation identifier
+
+By default, the bundle uses this identifier: `TWIG_DOC`
+
+To use another one:
+
+```yaml
+twig_doc:
+  doc_identifier: 'MY_DOC_IDENTIFIER'
+```
+
+In your component template, you can then mark up your documentation in the template:
+
+```twig
+{#MY_DOC_IDENTIFIER
+title: My component
+...
+MY_DOC_IDENTIFIER#}
+<div class="fancy-component"></div>
+```
+
+### Categories
+
+The bundle groups components into categories and optionally into sub-categories.
+
+Example:
+
+```yaml
+twig_doc:
+  categories:
+    - name: Buttons
+      sub_categories:
+        - Action
+        - Submit
+    - name: Headings
+    - name: Alerts
+...
+```
+
+The default category is always merged into the configuration.

docs/ComponentConfiguration.md

@@ -0,0 +1,79 @@
+### Component Configuration
+
+You have two possibilities to let the bundle know of your components:
+
+1. Directly in the template of the component itself (you should stick to this)
+2. In the config file
+
+You can use both possibilities, but it is recommended to use only one to avoid scattering documentation over different places.
+
+When you do not provide a category for the component, it will be added to the default-category.
+
+#### In Template
+
+We "abused" the comment tag from twig to allow the component configuration directly in the template.
+This won't hurt twig at all as comments are totally ignored by the twig-parser.
+
+When providing the config in the template, you do not need to provide the name, this is automatically resolved from the template file.
+
+```twig
+{#TWIG_DOC
+    title: Fancy Button
+    description: This is a really fancy button
+    category: Buttons
+    tags:
+      - button
+    parameters:
+      type: String
+      text: String
+    variations:
+      primary:
+        type: primary
+        text: Hello World
+      secondary:
+        type: secondary
+        text: Welcome to Hell!
+#TWIG_DOC}
+
+<button class="btn btn-{{ type }}">{{ text }}</button>
+```
+
+#### Config file
+
+This is only recommended for small sets of components.
+
+The bundle tries to resolve the path of the template in a compiler pass based on the name of the component.
+
+E.g.: name: Button -> bundle looks for a Button.html.twig
+
+For this to work, you need to ensure that your components are unique among all configured directories.
+
+```yaml
+...
+components:
+  - name: Button
+    title: Fancy Button
+    description: This is a really fancy button
+    category: Buttons
+    tags:
+      - button
+    parameters:
+      type: String
+      text: String
+    variations:
+      primary:
+        type: primary
+        text: Hello World
+      secondary:
+        type: secondary
+        text: Welcome to Hell!
+```
+
+Alternatively, you can provide a path for your component in the configuration (parameters are resolved automatically):
+
+```yaml
+...
+components:
+  - name: Button
+    path: '%twig.default_path%/snippets/FancyButton.html.twig'
+```

docs/Usage.md

@@ -0,0 +1,5 @@
+## Usage
+
+TODO
+- screenshots of UI
+- searching

phpunit.xml.dist

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
+         bootstrap="tests/bootstrap.php"
          cacheDirectory=".phpunit.cache"
          executionOrder="depends,defects"
          requireCoverageMetadata="true"
@@ -12,7 +12,7 @@
          displayDetailsOnTestsThatTriggerWarnings="true">
 
     <php>
-        <env name="APP_ENV" value="test" />
+        <env name="APP_ENV" value="test" force="true" />
         <server name="KERNEL_CLASS" value="Qossmic\TwigDocBundle\Tests\TestApp\Kernel" />
     </php>
 

src/Component/ComponentCategory.php

@@ -11,6 +11,8 @@
  */
 class ComponentCategory
 {
+    public const DEFAULT_CATEGORY = 'Components';
+
     private ?ComponentCategory $parent = null;
 
     #[Assert\Regex('/^\w+$/')]

src/Component/ComponentItem.php

@@ -25,6 +25,12 @@ class ComponentItem
     private array $variations;
     #[Assert\Valid]
     private ComponentCategory $category;
+    #[Assert\Length(max: 4096)]
+    #[Assert\NotBlank]
+    private string $projectPath;
+    #[Assert\Length(max: 4096)]
+    #[Assert\NotBlank]
+    private string $renderPath;
 
     public function getName(): string
     {
@@ -142,4 +148,28 @@ public function getMainCategory(): ComponentCategory
     {
         return $this->category->getParent() ?? $this->category;
     }
+
+    public function getProjectPath(): ?string
+    {
+        return $this->projectPath;
+    }
+
+    public function setProjectPath(?string $projectPath): self
+    {
+        $this->projectPath = $projectPath;
+
+        return $this;
+    }
+
+    public function getRenderPath(): ?string
+    {
+        return $this->renderPath;
+    }
+
+    public function setRenderPath(?string $renderPath): self
+    {
+        $this->renderPath = $renderPath;
+
+        return $this;
+    }
 }