[Icons] Docs: Merging HTML and Twig syntaxes

[ThomasLandauer]

Q	A
Bug fix?	no
New feature?	no
Docs?	yes
Issues
License	MIT

https://symfony.com/bundles/ux-icons/current/index.html

• The fact that you need symfony/ux-twig-component was explained three times.
• The section "HTML Syntax" was included twice: https://symfony.com/bundles/ux-icons/current/index.html#html-syntax and https://symfony.com/bundles/ux-icons/current/index.html#html-syntax-1
• Having the section "Icon Sets" between the Twig and the HTML syntax makes no sense IMO, so I started by moving the HTML syntax upwards.
• Then I thought that it's even better to merge these two code blocks:
  • This shows the differences between the syntaxes better
  • And presents the HTML syntax as an equal alternative (not some exotic experimental feature ;-)
• The default attribute config is pretty easy to understand, so it doesn't need a fullblown code sample; linking to the config section should be enough IMO.

[ThomasLandauer]

UX Icons is a bundle that does not require Twig Component.

Indeed, that's explained at https://github.com/symfony/ux/blob/b954ff73a6a48e2898a1310a6ea30d1e2395837b/src/Icons/doc/index.rst#L66

You suggestion here will delete/remove vital documentation about basic usage of this bundle.

I know that reviewing docs changes on GitHub is a nightmare :-) So just tell me what you think is missing, and I'll tell you where it is now.

This is not something anyone would benefit. And I must admit I'm not sure to understand your point / end goal on these recent PR.

My main goal is to explain stuff just once and not three times :-)

[ThomasLandauer]

What about having a single, top level "HTML Syntax" section, where this is the only place we talk about/show examples of it?

Yeah, I thought about that too. In the end, I went for the "mixed" code block, to present both as equally good alternatives.

But if you want, I can split them. This would make comparing the syntaxes harder. But later on (after people have decided for one), give them a nicer "reference".

[kbond]

I'm thinking of it in terms of "directing someone to the html syntax" - what section do I sent them to currently?

@smnandre wdyt?

[ThomasLandauer]

You mean for reference on the HTML syntax? I'd say just here: https://github.com/symfony/ux/blob/b954ff73a6a48e2898a1310a6ea30d1e2395837b/src/Icons/doc/index.rst#L59

Or do you mean "directing" them to switch to HTML syntax? (i.e. recommending it)

IMO, the entire syntax is so easy/lightweight, that after having written it 2-3 times, people won't need much reference anymore.

[kbond]

I think mixing syntaxes throughout the docs might be confusing. Better to show a consistent syntax, then "btw, you can use this alternate syntax"

[ThomasLandauer]

Uhm, there is no "throughout" anymore. The (almost) only other place with syntax is https://symfony.com/bundles/ux-icons/current/index.html#icon-aliases - which you just "urged" me to remove too (see https://github.com/symfony/ux/pull/2795#discussion_r2114885611 :-)

[ThomasLandauer]

I see that you have strong opinions.

So just take what you think is useful, and close/delete the rest.

[smnandre]

We're always open to improvements

Recent suggestions felt a bit mixed --some very valid points, others less aligned with concrete user needs or going against points we've already covered.

Thanks again for your time and input!

[javiereguiluz]

Folks, if there's interest, I think we could show both syntaxes at the same time, and allow user to select which one they prefer.

Same as we do in Symfony Docs, we could use a configuration-block like this:

.. configuration-block::

    .. code-block:: ux-twig

        {# Includes 'assets/icons/admin/user-profile.svg': #}
        {{ ux_icon('admin:user-profile') }}

    .. code-block:: ux-html

        {# Includes 'assets/icons/admin/user-profile.svg': #}
        <twig:ux:icon name="admin:user-profile" />

The ux-twig and ux-html labels are up to debate, but must be different from the ones used in Symfony (yaml, xml, php-attributes, etc.)

If you like this, tell us and we'd make the (minor) changes required in our RST support to add support for these two new code block labels. Thanks!

[kbond]

@javiereguiluz that's a great idea!

[smnandre]

@javiereguiluz I'd love this !

Twig vs UX ?