Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Icons] Improve setup instructions #2664

Merged
merged 1 commit into from
Apr 4, 2025
+19 −10
Merged

[Icons] Improve setup instructions #2664

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions src/Icons/doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,15 @@ Installation

$ composer require symfony/ux-icons

HTTP Client for On-Demand Icons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you plan to use provided icon sets, make sure that you have the HTTP client installed:

.. code-block:: terminal

$ composer require symfony/http-client
Comment on lines +22 to +26
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you use another type of block here, or even maybe just a paragraph?

I'd like to stay in line with the symfony.com documentation "standard", and only document here the strict minimum.

Too many information could give a false impression of complexity

It's a delicate art to not overwelm users with info when they do not need it yet, but also not falling in the opposite. (your issue is a proof of that!).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my thinking was that the optional dependencies are easy to overlook when not reading through the complete documentation chronologically. if the introduction explains what the component can do and what you need to install to do that, i think it is useful.

i can change this into a sub-paragraph if you think that is better - i felt it being so short an additional title is not necessarily helping. on the other hand, the title will show up in the ToC so it might get useful visibility when starting to look for reasons of the problem.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand your point of view. At the same time, I also have to consider the appeal of the documentation — first impressions matter.

If I land on a page that opens with multiple blocks of install commands, bash snippets, and config files, my first thought is often: "Wow, this package looks complicated to install."

But in this case, the vast majority of developers installing UX Icons just need to run composer req symfony/ux-icons, and everything is set up automatically.

I'm not saying we should ignore those who fall outside that category — but I also can't disregard the majority.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

of course, having a 15 step installation instructions is off-putting. but oversimplification is not helping either. i removed the part about ux-twig-component and made a separate subtitle for the http-client

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's that visible, maybe then we can remove it from the other parts ?

This use case is not the most common, and I'm not 100% convinced it requires multiple big blocks on the same page.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

honestly i think if we find a good solution for #2667, we can remove either this section or the ones below in the sections that rely on http client.


SVG Icons
---------

Expand Down Expand Up @@ -63,15 +72,6 @@ Loading Icons
and embeds the downloaded SVG contents in the template #}
{{ ux_icon('flowbite:user-solid') }}

.. note::

To search and download icons via `ux.symfony.com/icons`_, the ``symfony/http-client``
package must be installed in your application:

.. code-block:: terminal

$ composer require symfony/http-client

The ``ux_icon()`` function defines a second optional argument where you can
define the HTML attributes added to the ``<svg>`` element:

Expand All @@ -87,6 +87,15 @@ define the HTML attributes added to the ``<svg>`` element:
Icon Sets
~~~~~~~~~

.. note::

To use icons from icon sets via `ux.symfony.com/icons`_, the ``symfony/http-client``
package must be installed in your application:

.. code-block:: terminal

$ composer require symfony/http-client

There are many icon sets available, each with their own unique style and set of
icons, providing a wide range of icons for different purposes, while maintaining
a consistent look and feel across your application. Here are some of the most
Expand Down Expand Up @@ -166,7 +175,7 @@ HTML Syntax

In addition to the ``ux_icon()`` function explained in the previous sections,
this package also supports an alternative HTML syntax based on the ``<twig:ux:icon>``
tag:
tag if the ``symfony/ux-twig-component`` package is installed:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

Does feel like a duplicate of the tip 10 lines below.

What about moving it after the introduction sentence ? and before the code examples ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i duplicated it on purpose, becaues it is very important, and i think some people will rather see the box, while others rather read the text flow. alternatively we could even put it into the code block as a comment right before the first tag.

which introduction sentence do you mean? the "HTML Syntax" section only has one sentence until here? or you mean moving the ..tip to above the code? i can also do that.


.. code-block:: html

Expand Down