From bda417df10198c86fbe7e27c0212f7c795e535b6 Mon Sep 17 00:00:00 2001 From: tgresavage Date: Mon, 2 Oct 2023 16:03:11 -0400 Subject: [PATCH 01/11] docs: add instructions for custom SVG icons --- docs/user_guide/header-links.rst | 60 ++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 6b410f1ce..ce9d925fb 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -145,6 +145,18 @@ Image icons If you'd like to display an icon image that is not in the FontAwesome icons library, you may instead specify a URL or a path to a local image that will be used for the icon. +You may also use ``.svg`` images as if they were FontAwesome with a little additional setup. + +Bitmap image icons +~~~~~~~~~~~~~~~~~~ + +For all bitmap image icons such as ``.png``, ``.jpg``, etc., you must specify ``type`` as local. + +.. admonition:: Note regarding :literal:`.svg`'s + :class: note + + All icon images with ``"type": "local"`` are inserted into the document using ```` tags. + If you need features specific to objects in the ``svg`` class please see :ref:`svg image icons ` **To display an image on the web**, use ``"type": "url"``, and provide a URL to an image in the ``icon`` value. For example: @@ -188,6 +200,54 @@ For example: Use ``.svg`` images for a higher-resolution output that behaves similarly across screen sizes. +.. _svg-image-icons: + +SVG image icons +~~~~~~~~~~~~~~~ + +In order to make use of the full feature set of ``.svg`` images provided by HTML you will need +to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly straightforward process: + +#. Copy the contents of ``docs/_static/custom-icon.js`` into an appropriate directory of your documentation + source (typically ``source/js``) and rename the file however you like. + + .. literalinclude:: ../_static/custom-icon.js + :language: javascript + :emphasize-lines: 7, 13 + :linenos: + +#. Update the ``iconName`` (line 7 above) in your custom ``.js`` file to be one of our choosing + +#. Replace the path string (line 13 above) with the path which defines your custom icon +#. Add the relative path from your source directory to the custom javascript file to your ``conf.py``: + + .. code:: python + + html_js_files = [ + ... + "js/pypi-icon.js", + ... + ] + +#. Set up the icon link in the ``html_theme_options`` as a FontAwesome icon: + + .. code:: python + + html_theme_options = [ + ... + "icon_links": [ + { + "name": "PyPI", + "url": "https://www.pypi.org", + "icon": "fa-custom fa-pypi", + "type": "fontawesome", + }, + ], + ... + ] + +That's it, your icon will now be inserted as with the ```` tag and not the ````! You can reference your custom FontAwesome icon in CSS using ``fa-``! + .. _icon-link-shortcuts: Icon Link Shortcuts From d26f2029270072b749163c4607fbe7cd1e786adb Mon Sep 17 00:00:00 2001 From: tgresavage Date: Mon, 2 Oct 2023 16:08:26 -0400 Subject: [PATCH 02/11] docs: minor tweaks in SVG icon instructions --- docs/user_guide/header-links.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index ce9d925fb..4618082f3 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -246,7 +246,7 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s ... ] -That's it, your icon will now be inserted as with the ```` tag and not the ````! You can reference your custom FontAwesome icon in CSS using ``fa-``! +That's it, your icon will now be inserted as with the ```` tag and not ````! You can reference your custom FontAwesome icon in CSS using ``fa-``. .. _icon-link-shortcuts: From 6fbfa7ce6efd033ffad9e2f12fcca1af1d3d7d3f Mon Sep 17 00:00:00 2001 From: tgresavage Date: Mon, 2 Oct 2023 16:08:56 -0400 Subject: [PATCH 03/11] docs: some more tweaks to SVG icon instructions --- docs/user_guide/header-links.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 4618082f3..edb30d89c 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -246,7 +246,7 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s ... ] -That's it, your icon will now be inserted as with the ```` tag and not ````! You can reference your custom FontAwesome icon in CSS using ``fa-``. +That's it, your icon will now be inserted with the ```` tag and not ````! You can reference your custom FontAwesome icon in CSS using ``fa-``. .. _icon-link-shortcuts: From 49f328a42f717a983b8828577e91a706ecc53c9f Mon Sep 17 00:00:00 2001 From: gresavage Date: Tue, 3 Oct 2023 14:13:32 -0400 Subject: [PATCH 04/11] Update docs/user_guide/header-links.rst Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> --- docs/user_guide/header-links.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index edb30d89c..e970c1cb6 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -152,8 +152,7 @@ Bitmap image icons For all bitmap image icons such as ``.png``, ``.jpg``, etc., you must specify ``type`` as local. -.. admonition:: Note regarding :literal:`.svg`'s - :class: note +.. note:: Note regarding :literal:`.svg`'s All icon images with ``"type": "local"`` are inserted into the document using ```` tags. If you need features specific to objects in the ``svg`` class please see :ref:`svg image icons ` From bb319dd9c2dd6d09d87874ecc5e24eeeb489167f Mon Sep 17 00:00:00 2001 From: tgresavage Date: Tue, 3 Oct 2023 14:36:18 -0400 Subject: [PATCH 05/11] Change literalinclude to code-block in header links --- docs/user_guide/header-links.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index e970c1cb6..e9f953cae 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -207,17 +207,31 @@ SVG image icons In order to make use of the full feature set of ``.svg`` images provided by HTML you will need to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly straightforward process: -#. Copy the contents of ``docs/_static/custom-icon.js`` into an appropriate directory of your documentation - source (typically ``source/js``) and rename the file however you like. +#. Copy the contents of ``custom-icon.js`` - located within the ``docs`` tree - into an appropriate directory of your documentation + source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified - .. literalinclude:: ../_static/custom-icon.js - :language: javascript - :emphasize-lines: 7, 13 - :linenos: + .. sourcecode:: javascript + :emphasize-lines: 3,5,6,9 -#. Update the ``iconName`` (line 7 above) in your custom ``.js`` file to be one of our choosing + ... + prefix: "fa-custom", + iconName: "pypi", + icon: [ + 17.313, // viewBox width + 19.807, // viewBox height + [], // ligature + "e001", // unicode codepoint - private use area + "m10.383 0.2-3.239 ...", // string definined SVG path + ], + ... + + +#. Update the following file contents: + + #. ``iconName`` to be one of our choosing + #. Change the viewbox height and width to match that of your icon + #. Replace the SVG path string with the path which defines your custom icon -#. Replace the path string (line 13 above) with the path which defines your custom icon #. Add the relative path from your source directory to the custom javascript file to your ``conf.py``: .. code:: python From 248689141e50a4b2a4093003e4967fa5a76d5118 Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Mon, 16 Oct 2023 18:29:47 +0200 Subject: [PATCH 06/11] Update docs/user_guide/header-links.rst Co-authored-by: Daniel McCloy --- docs/user_guide/header-links.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index e9f953cae..537d16f4b 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -152,7 +152,7 @@ Bitmap image icons For all bitmap image icons such as ``.png``, ``.jpg``, etc., you must specify ``type`` as local. -.. note:: Note regarding :literal:`.svg`'s +.. note:: All icon images with ``"type": "local"`` are inserted into the document using ```` tags. If you need features specific to objects in the ``svg`` class please see :ref:`svg image icons ` From f30c75aef8af253af419363e9c942674f9091502 Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Wed, 18 Oct 2023 13:34:49 +0200 Subject: [PATCH 07/11] Update docs/user_guide/header-links.rst --- docs/user_guide/header-links.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 537d16f4b..46205cb1b 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -223,7 +223,6 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s "e001", // unicode codepoint - private use area "m10.383 0.2-3.239 ...", // string definined SVG path ], - ... #. Update the following file contents: From 12a1943f65281ae0ea1da54a6a85a1039d16a170 Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Wed, 18 Oct 2023 13:34:56 +0200 Subject: [PATCH 08/11] Update docs/user_guide/header-links.rst --- docs/user_guide/header-links.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 46205cb1b..9cf79ad29 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -210,10 +210,8 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s #. Copy the contents of ``custom-icon.js`` - located within the ``docs`` tree - into an appropriate directory of your documentation source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified - .. sourcecode:: javascript - :emphasize-lines: 3,5,6,9 - - ... + .. code:: javascript + prefix: "fa-custom", iconName: "pypi", icon: [ From 21f2407d381726e989e2a022f901efb94b3516f9 Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Wed, 18 Oct 2023 13:37:00 +0200 Subject: [PATCH 09/11] Update docs/user_guide/header-links.rst --- docs/user_guide/header-links.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 9cf79ad29..d96fc2073 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -212,15 +212,15 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s .. code:: javascript - prefix: "fa-custom", - iconName: "pypi", - icon: [ - 17.313, // viewBox width - 19.807, // viewBox height - [], // ligature - "e001", // unicode codepoint - private use area - "m10.383 0.2-3.239 ...", // string definined SVG path - ], + prefix: "fa-custom", + iconName: "pypi", + icon: [ + 17.313, // viewBox width + 19.807, // viewBox height + [], // ligature + "e001", // unicode codepoint - private use area + "m10.383 0.2-3.239 ...", // string definined SVG path + ], #. Update the following file contents: From d4a8ac8d516125d8c76fabb6d632f00f21aba93f Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Wed, 18 Oct 2023 13:39:24 +0200 Subject: [PATCH 10/11] Update docs/user_guide/header-links.rst --- docs/user_guide/header-links.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index d96fc2073..6abbd9074 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -211,7 +211,6 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified .. code:: javascript - prefix: "fa-custom", iconName: "pypi", icon: [ From 2162a25ce70456c9fca0f5315430b0b67ddf3c20 Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Wed, 18 Oct 2023 13:40:28 +0200 Subject: [PATCH 11/11] Update docs/user_guide/header-links.rst --- docs/user_guide/header-links.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst index 6abbd9074..0a87604f8 100644 --- a/docs/user_guide/header-links.rst +++ b/docs/user_guide/header-links.rst @@ -211,6 +211,7 @@ to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly s source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified .. code:: javascript + prefix: "fa-custom", iconName: "pypi", icon: [