diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 520b3a063..67fd2ad12 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -134,6 +134,7 @@ URIs? URL utils uv +validator Valkey venv VM's diff --git a/docs/howto/add-an-icon.rst b/docs/howto/add-an-icon.rst new file mode 100644 index 000000000..ed6548f1a --- /dev/null +++ b/docs/howto/add-an-icon.rst @@ -0,0 +1,104 @@ +.. meta:: + :description: How to create, validate, and add an icon to a charm's Charmhub page. + Includes a demo of using Inkscape to draw the icon. + +.. _manage-icons: +.. _how-to-add-an-icon: + +Add an icon to Charmhub +======================= + +Creating a custom icon for your charm is a great way to make it stand out on Charmhub. +This guide works through creating, validating, and adding an icon to your charm's +Charmhub page. + + +Install prerequisites +--------------------- + +You can create the icon with any vector graphics editor, but this guide works through +the process with Inkscape. If you're following along step by step, `install Inkscape +`__. + +Next, right-click on the following link to save the `icon template +`__ to your machine. Leave the file name +as ``icon.svg``. + + +Draw the icon in Inkscape +------------------------- + +Open Inkscape and load the icon template you downloaded in the previous step. + +To change the icon's background color, start by pressing :kbd:`Ctrl` + :kbd:`Shift` + +:kbd:`L` and clicking on :guilabel:`BACKGROUND` in the resulting tab. + +.. figure:: images/add-an-icon/layer-select.png + :alt: Layer selection interface in the Inkscape editor + +With the background layer selected, press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`F` to open +the Fill and Stroke interface. You can then select a color for the background. + +.. figure:: images/add-an-icon/color-select.png + :alt: Fill and stroke selection interface in Inkscape + +Next, go back to the layer selection window and select the :guilabel:`PLACE LOGO HERE` +layer. If you already have a vector image icon, drag it into this layer. If you have +a bitmap image, you'll need to convert it into a vector file first. + +If you don't have an existing logo, you can use the drawing tools in Inkscape to create +one from scratch. + +Once everything is to your liking, rename this layer to something more meaningful, like +:guilabel:`LOGO` or :guilabel:`ICON`. + +.. figure:: images/add-an-icon/import-logo.png + :alt: Draw something + +Once you're happy with your icon, press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`S` and save +the file as ``icon.svg`` in the directory containing your charm's project file. + + +Validate the icon +----------------- + +Go to the `Charmhub icon validator `_ and upload +your icon to check for any issues with its file type or dimensions. If you used the +provided template, this should pass without any issues. + +To fix issues related to the icon's size, go back into Inkscape, press :kbd:`Ctrl` + +:kbd:`Shift` + :kbd:`D`, and set the height and width to 100 pixels. + + +.. _how-to-pack-the-icon-in-the-charm: + +Pack the icon in the charm +-------------------------- + +For the icon to be displayed on Charmhub, it needs to be packed into the final charm +artifact. Ensure that the ``icon.svg`` file is present in the directory containing your +charm's project file. + +If your charm's main part uses the Charm plugin, the icon will be packed in the final +charm by default. + +For every other plugin, you need to explicitly add the ``icon.svg`` file to the charm +by adding a new part using the :ref:`craft_parts_dump_plugin` to your project file. + +.. code-block:: yaml + :caption: charmcraft.yaml + + parts: + icon: + plugin: dump + source: . + stage: + - icon.svg + +The next time you :ref:`publish the charm ` to its default track's +``stable`` channel, the icon will be displayed on Charmhub. Charmhub only updates the +charm's metadata on releases to the ``stable`` channel. + +If you aren't ready for a ``stable`` release, you can add the icon by releasing and +then rolling back a revision. However, it's generally recommended you wait until +the charm is ready for a true ``stable`` release. diff --git a/docs/howto/images/add-an-icon/color-select.png b/docs/howto/images/add-an-icon/color-select.png new file mode 100644 index 000000000..48c4b13ed Binary files /dev/null and b/docs/howto/images/add-an-icon/color-select.png differ diff --git a/docs/howto/images/add-an-icon/import-logo.png b/docs/howto/images/add-an-icon/import-logo.png new file mode 100644 index 000000000..5465c4eea Binary files /dev/null and b/docs/howto/images/add-an-icon/import-logo.png differ diff --git a/docs/howto/images/add-an-icon/layer-select.png b/docs/howto/images/add-an-icon/layer-select.png new file mode 100644 index 000000000..4e972e4d4 Binary files /dev/null and b/docs/howto/images/add-an-icon/layer-select.png differ diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 798fe2a7e..c90a08534 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -39,7 +39,7 @@ publish it to Charmhub, and manage its releases. - :ref:`how-to-build-remotely` - :ref:`manage-the-current-charmhub-user` - :ref:`manage-names` -- :ref:`manage-icons` +- :ref:`how-to-add-an-icon` - :ref:`manage-charm-revisions` - :ref:`manage-tracks` - :ref:`manage-channels` @@ -84,6 +84,6 @@ update a charm to the new base: manage-revisions manage-channels manage-tracks - manage-icons + add-an-icon Migrate plugins Migrate bases diff --git a/docs/howto/manage-icons.rst b/docs/howto/manage-icons.rst deleted file mode 100644 index e597be57b..000000000 --- a/docs/howto/manage-icons.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. _manage-icons: - -.. meta:: - :description: How to create, validate, and add an icon to a charm's Charmhub page. Includes a demo of using Inkscape to draw the icon. - -Manage icons -============ - -This guide shows how to create, validate, and add an icon to your charm's -Charmhub page. - -Learn about icon requirements and best practices ------------------------------------------------- - -You can learn about icon requirements and best practices from the -:ref:`icon SVG file ` reference. - -Create an icon --------------- - -Before you start you will need: - -- A vector graphic editor. We strongly recommend the cross-platform and - most excellent `Inkscape `__ for all your - vector graphic needs. -- `The template - file. `__ - (right-click > Save link as…) -- An existing logo you can import, or the ability to draw one in - Inkscape. - -Once you have those, fire up Inkscape and we can begin! - -1. Open the template -~~~~~~~~~~~~~~~~~~~~ - -From Inkscape load the ``icon.svg`` file. Select the Layer called -“Background Circle”, either from the drop down at the bottom, or from -the layer dialog. - -.. figure:: https://assets.ubuntu.com/v1/067f88a5-manage-icons-create-1.png - :alt: Open the template - - Open the template - -3. Add colour -~~~~~~~~~~~~~ - -In the menu, select **Object** and then **Fill and Stroke** to adjust -the colour. - -.. figure:: https://assets.ubuntu.com/v1/0bff03c4-manage-icons-create-2.png - :alt: Add color - - -2. Draw something -~~~~~~~~~~~~~~~~~ - -Draw your shape within the circle. If you already have a vector logo, -you can import it and scale it within the guides. Inkscape also has -plenty of drawing tools for creating complex images. - -If you import a bitmap image to use, be sure to convert it into a vector -file and delete the bitmap. - -.. figure:: https://assets.ubuntu.com/v1/2ef5c7f5-manage-icons-create-3.png - :alt: Draw something - -*Cloud icon: “Cloud by :vale-ignore:`unlimicon` from the Noun Project” [CC BY]* - -Validate an icon ----------------- - -You can validate your icon at -`charmhub.io/icon-validator `_. The -page checks the most basic issues that prevent icons working. - -.. figure:: https://assets.ubuntu.com/v1/cc23c12a-manage-icons-validate.png - :alt: Validate - -Add an icon to its charm's Charmhub page ----------------------------------------- - -To add the icon to the charm's Charmhub page, first save the icon as ``icon.svg`` in -the root directory of the charm. - -If the charm uses the Charm plugin, the icon will be included in it. -Otherwise, use the Dump plugin to include the icon. See guidance -for the :ref:`Poetry plugin `, -:ref:`Python plugin `, or -:ref:`uv plugin `. - -Next, :ref:`publish the charm to a channel ` -of the form ``/stable`` (e.g., ``latest/stable``). Note that the -track that you publish the icon to needs to be the default track for the -icon to be displayed on Charmhub. Please raise a -`CharmHub request `_ -on Discourse to set a track as the default track. - -.. note:: - That is because Charmhub only updates the metadata for a charm on stable channel - releases (`by design - `_). - So either release the revision with the icon to a ``stable`` channel and then - roll it back, or wait until your charm is ready for a "stable" ``stable`` release. diff --git a/docs/howto/migrate-plugins/charm-to-poetry.rst b/docs/howto/migrate-plugins/charm-to-poetry.rst index 6fd212bfc..6ed77614c 100644 --- a/docs/howto/migrate-plugins/charm-to-poetry.rst +++ b/docs/howto/migrate-plugins/charm-to-poetry.rst @@ -89,10 +89,10 @@ from all loaded charmlibs. Include extra files ------------------- -A Poetry plugin only includes the contents of the ``src`` and ``lib`` directories -as well as the generated virtual environment. If other files such as a charm's icon -were previously included from the main directory, stage them in the charm in a new part -that uses the :ref:`craft_parts_dump_plugin`: +A Poetry plugin only includes the contents of the ``src`` and ``lib`` directories as +well as the generated virtual environment. Other files, such as the +:ref:`icon-svg-file`, are no longer included by default and need to be explicitly packed +in the charm with a new part that uses the :ref:`craft_parts_dump_plugin`. .. code-block:: yaml :caption: charmcraft.yaml diff --git a/docs/howto/migrate-plugins/charm-to-python.rst b/docs/howto/migrate-plugins/charm-to-python.rst index 2b7219222..f785065b3 100644 --- a/docs/howto/migrate-plugins/charm-to-python.rst +++ b/docs/howto/migrate-plugins/charm-to-python.rst @@ -110,10 +110,10 @@ that generates ``requirements.txt``. Include extra files ------------------- -The Python plugin only includes the contents of the ``src`` and ``lib`` directories -as well as the generated virtual environment. If other files such as a charm's icon -were previously included from the main directory, stage them in the charm in a new part -that uses the :ref:`craft_parts_dump_plugin`: +The Python plugin only includes the contents of the ``src`` and ``lib`` directories as +well as the generated virtual environment. Other files, such as the +:ref:`icon-svg-file`, are no longer included by default and need to be explicitly packed +in the charm with a new part that uses the :ref:`craft_parts_dump_plugin`. .. code-block:: yaml :caption: charmcraft.yaml diff --git a/docs/howto/migrate-plugins/charm-to-uv.rst b/docs/howto/migrate-plugins/charm-to-uv.rst index 02ddf1b06..bb8846371 100644 --- a/docs/howto/migrate-plugins/charm-to-uv.rst +++ b/docs/howto/migrate-plugins/charm-to-uv.rst @@ -161,10 +161,10 @@ Likewise, optional dependencies under the ``pyproject.toml`` key Include extra files ------------------- -The uv plugin only includes the contents of the ``src`` and ``lib`` directories -as well as the generated virtual environment. If other files such as a charm's icon -were previously included from the main directory, stage them in the charm in a new part -that uses the :ref:`craft_parts_dump_plugin`: +The uv plugin only includes the contents of the ``src`` and ``lib`` directories as well +as the generated virtual environment. Other files, such as the :ref:`icon-svg-file`, are +no longer included by default and need to be explicitly packed in the charm with a new +part that uses the :ref:`craft_parts_dump_plugin`. .. code-block:: yaml :caption: charmcraft.yaml diff --git a/docs/redirects.txt b/docs/redirects.txt index 646518142..adc1f4da6 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -6,6 +6,7 @@ "howto/set-up-charmcraft.rst" "howto/manage-charmcraft.rst" "howto/install-charmcraft.rst" "howto/manage-charmcraft.rst" +"howto/manage-icons.rst" "howto/add-an-icon.rst" "howto/manage-parts.rst" "reference/parts/index.rst" "tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst" "tutorial/kubernetes-charm-django.rst" "tutorial/write-your-first-kubernetes-charm-for-a-flask-app.rst" "tutorial/kubernetes-charm-flask.rst" diff --git a/docs/reference/files/icon-svg-file.rst b/docs/reference/files/icon-svg-file.rst index 12f5f1d50..20edd9747 100644 --- a/docs/reference/files/icon-svg-file.rst +++ b/docs/reference/files/icon-svg-file.rst @@ -1,3 +1,6 @@ +.. meta:: + :description: Reference for the ``icon.svg`` file, including its required dimensions, best practices, and examples. + .. _icon-svg-file: ``icon.svg`` file @@ -44,23 +47,8 @@ Examples Including the file ------------------ -If your file is not in your project directory but not included in the charm, you can -use the :ref:`craft_parts_dump_plugin` to include this file in your charm. - -.. dropdown:: Example - - This example is the :ref:`charmcraft-yaml-key-parts` key of a project file that uses - the :ref:`craft_parts_poetry_plugin` to build a charm, augmented to add the charm's - ``icon.svg`` file. - - .. code-block:: yaml +If your charm's main part uses the Charm plugin, the ``icon.svg`` file is packed in the +final charm by default if included in the same directory as your project file. - parts: - my-charm: - plugin: poetry - source: . - icon: - plugin: dump - source: . - stage: - - icon.svg +If your charm's main part uses the Python, Poetry, or uv plugin, the ``icon.svg`` file +must be :ref:`packed in the charm manually `.