Skip to content

Commit f3c1607

Browse files
davidhoelzeldavidhoelzel
authored
Documentation in template files (#6)
provides possibility to add documentation in templates with a twig-comment: {#TWIG_DOC ... TWIG_DOC#}
1 parent 7125d6e commit f3c1607

44 files changed

Lines changed: 1265 additions & 256 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
/var/
22
/vendor/
3+
/report/
34
.phpunit.cache
5+
.phpunit.result.cache
46
composer.lock
57
.php-cs-fixer.cache

‎README.md‎

Lines changed: 16 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,20 @@
11
## Twic Doc Bundle
22

3-
Allows you to create an overview for your Twig Components, be it either UX-Components, UX-Live-Components or simple snippet templates.
3+
[![Image](docs/resources/images/qossmic.png)](https://qossmic.com) Brought to you by qossmic!
44

5-
Components will be grouped in categories and optional sub-categories.
5+
1. [Installation](#installation)
6+
2. Configuration
7+
1. [Bundle Configuration](docs/BundleConfiguration.md)
8+
2. [Component Configuration](docs/ComponentConfiguration.md)
9+
3. [Routing](#routing)
10+
4. [Customization](#customizing-the-design)
11+
5. [Usage](docs/Usage.md)
12+
13+
---
614

7-
The categories must be configured in the bundle-configuration, see below.
15+
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.
16+
17+
Components will be grouped in categories and optional sub-categories.
818

919
### Installation
1020

@@ -38,110 +48,8 @@ twig_doc:
3848
# or for localized: prefix: /{_locale}/twig/doc/
3949
```
4050

41-
### Template
42-
43-
To use your design in the documentation, you have to override the component template.
44-
45-
Create a template in your project: templates/bundles/TwigDocBundle/component.html.twig
46-
47-
```twig
48-
{% extends '@!TwigDoc/component.html.twig' %}
49-
50-
{% block stylesheets %}
51-
<link rel="stylesheet" href="{{ asset('css/your-styles.css') }}">
52-
{% endblock %}
53-
```
54-
55-
#### Customizing the documentation
56-
57-
If you want to customize the documentation, you can override the template.
58-
59-
Create a template in your project: templates/bundles/TwigDocBundle/documentation.html.twig
60-
61-
```twig
62-
{% extends '@!TwigDoc/documentation.html.twig' %}
63-
64-
{% block stylesheets %}
65-
<link rel="stylesheet" href="{{ asset('css/your-styles.css') }}">
66-
{% endblock %}
67-
```
68-
69-
### Configuration
51+
### Customizing the design
7052

71-
Create a config file: configs/packages/twig_doc.yaml
53+
To customize the design of the documentation, you can override any template of the bundle in your project.
7254

73-
#### Configure categories
74-
75-
```yaml
76-
twig_doc:
77-
categories:
78-
- name: Button
79-
sub_categories:
80-
- Action
81-
- Submit
82-
- name: Heading
83-
- name: Notification
84-
sub_categories:
85-
- Alert
86-
- Flash
87-
#... component config
88-
```
89-
90-
#### Example for a Twig UX-Component
91-
92-
```yaml
93-
twig_doc:
94-
#... categories config
95-
components:
96-
- name: ActionButton # will render %kernel.project_dir%/templates/components/ActionButton.html.twig
97-
title: Action Button
98-
description: An Action button
99-
category: Buttons
100-
sub_category: Action
101-
tags:
102-
- buttons
103-
parameters:
104-
color: String
105-
text: String
106-
link: String
107-
variations:
108-
secondary:
109-
color: secondary
110-
text: Secondary Button
111-
link: '#'
112-
primary:
113-
color: primary
114-
text: Primary Button
115-
link: '#'
116-
```
117-
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).
118-
119-
#### Example for a non ux-twig-component
120-
121-
The only difference is that non-ux components use another default-path and the naming is not specified.
122-
123-
```yaml
124-
twig_doc:
125-
#... categories config
126-
components:
127-
- name: snippets/alert # will render %kernel.project_dir%/templates/snippets/alert.html.twig
128-
title: Alert
129-
description: non twig-ux-component component
130-
category: Notification
131-
sub_category:
132-
- Alert
133-
tags:
134-
- highlight
135-
- nameIt
136-
parameters:
137-
type: String
138-
msg: String
139-
variations:
140-
primary:
141-
type: primary
142-
msg: Primary Alert
143-
danger:
144-
type: danger
145-
msg: Danger Alert
146-
```
147-
The bundle will look for this template in the twig template folder (default: %kernel.project_dir%/templates/COMPONENT_NAME.html.twig).
55+
See: [How to override any Part of a Bundle](https://symfony.com/doc/current/bundles/override.html)

‎composer.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,14 @@
1818
"php": ">=8.2",
1919
"symfony/framework-bundle": "^6.4|^7.0",
2020
"symfony/validator": "^6.4|^7.0",
21-
"symfony/twig-bundle": "^6.4|^7.0"
21+
"symfony/twig-bundle": "^6.4|^7.0",
22+
"symfony/yaml": "^6.4|^7.0"
2223
},
2324
"require-dev": {
2425
"phpunit/phpunit": "^10.5",
2526
"symfony/browser-kit": "^6.4|^7.0",
2627
"symfony/css-selector": "^6.4|^7.0",
28+
"symfony/dom-crawler": "^6.4|^7.0",
2729
"friendsofphp/php-cs-fixer": "^3.51"
2830
}
2931
}

‎docs/BundleConfiguration.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
## Configuring the bundle
2+
3+
When you do not want to customize, you do not need any config file.
4+
5+
The bundle provides following defaults:
6+
7+
```yaml
8+
twig_doc:
9+
doc_identifier: TWIG_DOC
10+
directories:
11+
- '%twig.default_path%/components'
12+
categories:
13+
- name: Components
14+
```
15+
16+
### Directories
17+
18+
By default, the bundle looks for your components in this directory: `%twig.default_path%/components`
19+
20+
You can provide additional directories in the config-file:
21+
22+
```yaml
23+
twig_doc:
24+
directories:
25+
- '%twig.default_path%/snippets'
26+
- '%kernel.project_dir%/resources/components'
27+
```
28+
29+
### Documentation identifier
30+
31+
By default, the bundle uses this identifier: `TWIG_DOC`
32+
33+
To use another one:
34+
35+
```yaml
36+
twig_doc:
37+
doc_identifier: 'MY_DOC_IDENTIFIER'
38+
```
39+
40+
In your component template, you can then mark up your documentation in the template:
41+
42+
```twig
43+
{#MY_DOC_IDENTIFIER
44+
title: My component
45+
...
46+
MY_DOC_IDENTIFIER#}
47+
<div class="fancy-component"></div>
48+
```
49+
50+
### Categories
51+
52+
The bundle groups components into categories and optionally into sub-categories.
53+
54+
Example:
55+
56+
```yaml
57+
twig_doc:
58+
categories:
59+
- name: Buttons
60+
sub_categories:
61+
- Action
62+
- Submit
63+
- name: Headings
64+
- name: Alerts
65+
...
66+
```
67+
68+
The default category is always merged into the configuration.

‎docs/ComponentConfiguration.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
### Component Configuration
2+
3+
You have two possibilities to let the bundle know of your components:
4+
5+
1. Directly in the template of the component itself (you should stick to this)
6+
2. In the config file
7+
8+
You can use both possibilities, but it is recommended to use only one to avoid scattering documentation over different places.
9+
10+
When you do not provide a category for the component, it will be added to the default-category.
11+
12+
#### In Template
13+
14+
We "abused" the comment tag from twig to allow the component configuration directly in the template.
15+
This won't hurt twig at all as comments are totally ignored by the twig-parser.
16+
17+
When providing the config in the template, you do not need to provide the name, this is automatically resolved from the template file.
18+
19+
```twig
20+
{#TWIG_DOC
21+
title: Fancy Button
22+
description: This is a really fancy button
23+
category: Buttons
24+
tags:
25+
- button
26+
parameters:
27+
type: String
28+
text: String
29+
variations:
30+
primary:
31+
type: primary
32+
text: Hello World
33+
secondary:
34+
type: secondary
35+
text: Welcome to Hell!
36+
#TWIG_DOC}
37+
38+
<button class="btn btn-{{ type }}">{{ text }}</button>
39+
```
40+
41+
#### Config file
42+
43+
This is only recommended for small sets of components.
44+
45+
The bundle tries to resolve the path of the template in a compiler pass based on the name of the component.
46+
47+
E.g.: name: Button -> bundle looks for a Button.html.twig
48+
49+
For this to work, you need to ensure that your components are unique among all configured directories.
50+
51+
```yaml
52+
...
53+
components:
54+
- name: Button
55+
title: Fancy Button
56+
description: This is a really fancy button
57+
category: Buttons
58+
tags:
59+
- button
60+
parameters:
61+
type: String
62+
text: String
63+
variations:
64+
primary:
65+
type: primary
66+
text: Hello World
67+
secondary:
68+
type: secondary
69+
text: Welcome to Hell!
70+
```
71+
72+
Alternatively, you can provide a path for your component in the configuration (parameters are resolved automatically):
73+
74+
```yaml
75+
...
76+
components:
77+
- name: Button
78+
path: '%twig.default_path%/snippets/FancyButton.html.twig'
79+
```

‎docs/Usage.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Usage
2+
3+
TODO
4+
- screenshots of UI
5+
- searching

‎docs/resources/images/qossmic.png‎

1.38 KB
Loading

‎phpunit.xml.dist‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
33
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
4-
bootstrap="vendor/autoload.php"
4+
bootstrap="tests/bootstrap.php"
55
cacheDirectory=".phpunit.cache"
66
executionOrder="depends,defects"
77
requireCoverageMetadata="true"
@@ -12,7 +12,7 @@
1212
displayDetailsOnTestsThatTriggerWarnings="true">
1313

1414
<php>
15-
<env name="APP_ENV" value="test" />
15+
<env name="APP_ENV" value="test" force="true" />
1616
<server name="KERNEL_CLASS" value="Qossmic\TwigDocBundle\Tests\TestApp\Kernel" />
1717
</php>
1818

‎src/Component/ComponentCategory.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
*/
1212
class ComponentCategory
1313
{
14+
public const DEFAULT_CATEGORY = 'Components';
15+
1416
private ?ComponentCategory $parent = null;
1517

1618
#[Assert\Regex('/^\w+$/')]

‎src/Component/ComponentItem.php‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,12 @@ class ComponentItem
2525
private array $variations;
2626
#[Assert\Valid]
2727
private ComponentCategory $category;
28+
#[Assert\Length(max: 4096)]
29+
#[Assert\NotBlank]
30+
private string $projectPath;
31+
#[Assert\Length(max: 4096)]
32+
#[Assert\NotBlank]
33+
private string $renderPath;
2834

2935
public function getName(): string
3036
{
@@ -142,4 +148,28 @@ public function getMainCategory(): ComponentCategory
142148
{
143149
return $this->category->getParent() ?? $this->category;
144150
}
151+
152+
public function getProjectPath(): ?string
153+
{
154+
return $this->projectPath;
155+
}
156+
157+
public function setProjectPath(?string $projectPath): self
158+
{
159+
$this->projectPath = $projectPath;
160+
161+
return $this;
162+
}
163+
164+
public function getRenderPath(): ?string
165+
{
166+
return $this->renderPath;
167+
}
168+
169+
public function setRenderPath(?string $renderPath): self
170+
{
171+
$this->renderPath = $renderPath;
172+
173+
return $this;
174+
}
145175
}

0 commit comments

Comments
 (0)