Better support for SVGs in icon links

[gresavage]

I am currently struggling to get the same behavior between a local SVG and a FontAwesome SVG.

I have my CSS set up to change the color of each icon to the flagship color of each destination. E.G #2496ED for docker, #FC6D26 for Gitlab, etc. However one of the icons I'm using is local because FontAwesome doesn't currently have it in its repertoire.

I see that local images are inserted into the HTML differently than a FontAwesome one so SVGs end up losing a lot of their functionality. In my case being able to have the fill="currentColor" behave appropriately.

I would like to propose that SVGs be able to be placed into the HTML for icon links the same way as FontAwesome ones - whether they reside on the web or locally. In my opinion, it's as simple as checking the extension of the file/url. Alternatively an additional type: svg could be handled.

[12rambau]

It's actually already possible to use a custom svg icon and we are doing it in ou own documentation for the pypi icon. It was done in #1250.

• copy the structure of the custom-icon.js file and replace the data by your svg
• add it to the html_js files in your conf.py
• use it as a fa normal icon

Let me know if it works. If it's the case and you have the time to write down a small documentation PR it would be wonderful.

[gresavage]

Wow! Thank you so much

…

On Fri, Sep 29, 2023, 01:35 Rambaud Pierrick ***@***.***> wrote: It's actually already possible to use a custom svg icon and we are doing it in ou own documentation for the pypi icon. It was done in #1250 <#1250>. - copy the structure of the custom-icon.js file and replace the data by your svg - add it to the html_js files in your conf.py - use it as a fa normal icon Let me know if it works. If it's the case and you have the time to write down a small documentation PR it would be wonderful. — Reply to this email directly, view it on GitHub <#1487 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB45WG4BXOWIMXSW5CFWLYLX4ZM2BANCNFSM6AAAAAA5LUU3TI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[gresavage]

@12rambau this worked like a charm - I will try to get a PR for an update to the documentation in sometime this weekend

[12rambau]

I'm reopening the issue as I think the documentation would be beneficial for everyone !

[gresavage]

So the good news is that I've got the project forked and I've updated the documentation but I can't, for the life of me, get the docs to build. Neither manually setting up a virtual environment nor using nox works. I keep getting an error in AutoAPI. This happens even from a fresh clone. Below is the output of nox -s docs

nox > sphinx-build -b=html docs/ docs/_build/html -v -w warnings.txt
Running Sphinx v5.3.0
Adding copy buttons to code blocks...
locale_dir /home/tgresavage/Projects/pydata-sphinx-theme/docs/locales/en/LC_MESSAGES does not exists
[autosummary] generating autosummary for: community/contributors.md, community/index.md, community/inspiration.md, community/practices/merge.md, community/practices/release.md, community/practices/versions.md, community/setup.md, community/structure.md, community/topics/accessibility.md, community/topics/assets.md, ..., user_guide/page-toc.rst, user_guide/performance.rst, user_guide/readthedocs.md, user_guide/search.rst, user_guide/source-buttons.rst, user_guide/static_assets.md, user_guide/styling.rst, user_guide/theme-elements.md, user_guide/version-dropdown.rst, user_guide/web-components.rst
[AutoAPI] Reading files... [ 12%] /home/tgresavage/Projects/pydata-sphinx-theme/src/pydata_sphinx_theme/edit_this_page.py                                                            
Traceback (most recent call last):
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/extension.py", line 153, in run_autoapi
    if sphinx_mapper_obj.load(
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/mappers/python/mapper.py", line 300, in load
    data = self.read_file(path=path, dir_root=dir_root)
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/mappers/python/mapper.py", line 318, in read_file
    parsed_data = Parser().parse_file(path)
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/mappers/python/parser.py", line 41, in parse_file
    return self._parse_file(
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/mappers/python/parser.py", line 38, in _parse_file
    return self.parse(node)
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/mappers/python/parser.py", line 265, in parse
    data = parse_func(node)
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/autoapi/mappers/python/parser.py", line 240, in parse_module
    "doc": _prepare_docstring(node.doc or ""),
AttributeError: 'Module' object has no attribute 'doc'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/sphinx/application.py", line 262, in __init__
    self._init_builder()
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/sphinx/application.py", line 335, in _init_builder
    self.events.emit('builder-inited')
  File "/home/tgresavage/Projects/pydata-sphinx-theme/.nox/docs/lib/python3.10/site-packages/sphinx/events.py", line 105, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function run_autoapi at 0x7fc3ab2c9990> for event 'builder-inited' threw an exception (exception: 'Module' object has no attribute 'doc')

Extension error (autoapi.extension):
Handler <function run_autoapi at 0x7fc3ab2c9990> for event 'builder-inited' threw an exception (exception: 'Module' object has no attribute 'doc')
nox > Command sphinx-build -b=html docs/ docs/_build/html -v -w warnings.txt failed with exit code 2
nox > Session docs failed.

[12rambau]

that's related to this issue: #1474 and the solution is in the pipe but not yet reviewed (#1482).

As we don't want to use too much of your time simply push your changes, I'll review them by hand, I know the docs structure by heart.

[gresavage]

Very good! Then I just pushed my changes and started the PR