Feature request: Adding html_touch_icon setting.

AtsushiSakai commented 4 years ago

Is your feature request related to a problem? Please describe. When I create a document with Sphinx, I want to refer it from iOS or Android. But when I bookmark the doc link, it is not beautiful because it does not have an icon for it.

Describe the solution you'd like Sphinx already has "html_fabicon" setting. Using the similar way, it would be great to add a "html_touch_icon" or something like that for setting apple touch icon tag in setup.py.

tk0miya commented 4 years ago

+1. It would be better to support other icons because there are many kinds of icons. https://gist.github.com/hsquareweb/2210110

bienchen commented 4 years ago

Hello, is somebody already working on this? I could use the same feature in my project, plus a bunch of other "fancy favicons". If nobody has his already covered, I could prepare something.

Cheers,

B

tk0miya commented 4 years ago

I guess nobody is working on this yet. I tried to consider an option for this once. But I could not find a good name for this because there are many kinds of icon tags... So any ideas and PRs are welcome :-) https://gist.github.com/hsquareweb/2210110

bienchen commented 4 years ago

I have now a version that sets the touch icon for the latest iOS version. For me that’s enough. Just need to write the documentation, then I can place a merge request. I still want to do the Windows tile and Android icon.

Sent by my Toaster.

Am 27.09.2020 um 15:23 schrieb Takeshi KOMIYA notifications@github.com:

I guess nobody is working on this yet. I tried to consider an option for this once. But I could not find a good name for this because there are many kinds of icon tags... So any ideas and PRs are welcome :-) https://gist.github.com/hsquareweb/2210110

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

tk0miya commented 3 years ago

Finally, I thought most users do not want to configure the icon in detail. So it would be better to give an image file and convert it to the appropriate size and generate tags.

html_icon = 'path/to/icon.png'  # the icon will be converted to the appropriate size of touch icons, ms-application squares and so on.

It would be better to provide a way to configure them in detail. But it's not too late if somebody will request it.

tcmetzger commented 3 years ago

@tk0miya To continue our discussion from https://github.com/sphinx-doc/sphinx/pull/8249:

Interface is indeed a big question here, given that favicons come in all sorts of shapes and flavors. I think we have to draw the line somewhere and acknowledge that the asolute power users will extend any theme anyways if they need support for every icon format imaginable. For this reason, I'd propose to stick with the configuration format we use in pydata sphinx theme (https://github.com/pydata/pydata-sphinx-theme/pull/359), i.e. making rel, sizes, and href configurable in conf.py (with rel as an optional variable defaulting to icon). We could also add some more optional config variables, such as tag (defaults to link). I'd say the only variables that can't have defaults are sizes and href.

EDIT: this is an example of what the favicon config looks like for pydata-sphinx-theme:

   html_theme_options = {
      "favicons": [
         {
            "rel": "icon",
            "sizes": "16x16",
            "href": "https://secure.example.com/favicon/favicon-16x16.png",
         },
      ]
   }

tk0miya commented 3 years ago

Do you have idea to support <meta> style tags (ex. favicons for msapplications)? And what do you think the my last comment (auto conversion).

tcmetzger commented 3 years ago

Well, where should the line be drawn to just letting the user include a freeform string in the <head> to include any kind of favicon (or really, anything?). I think that power users will inject custom meta tags in any way they like, anyways - so I think having support for additional <link>-based favicons would be sufficient (at least for the first iteration of this feature). Following the original idea in this issue, I think it makes the most sense to offer some simple config values for someone who wants a little more than just the standard html_favicon, but also wants to keep things reasonably quick and simple (the docs for this feature could even include some ideas of how to inject even more complex favicon code, such as MS's browserconfig.xml, etc.).

Automating some aspects of this would certainly be nice. But to support a good number of favicon-formats, the existing html_favicon would have to have a minimum file size of at least 512x512px, and I believe that would make the existing favicon too complex (and break lots of people's existing configurations). I think what the original issue is aiming for, and what I'd like to see as well, is having the option to easily define some additional favicons. Whoever wants to have these very advanced kinds of favicons will most likely be able to generate the required filesizes themselves - and would most likely also appreciate having full control over each of these files (which algorithms to use for shrinking a 512x512px image to a 32x32 one, or compression, for example). However, I'd like to think about making sizes an optional property and then just check the dimensions of a supplied icon file to automatically fill in sizes, that could be a nifty little time-saver!

I think what we are talking about here is a middle-of-the-road approach: Most users probably won't worry much about favicons and will just be happy to use html_favicon as it is. At the opposite end of the spectrum, there are some power users who have very specific ideas of how they want to optimize their page and who will inject custom code to get exactly what they want. But then there are also some people in the middle who want more than just html_favicon but also don't want to get into customizing their template too heavily. Those people are who I'd have in mind for a feature like this.

It is really just a matter of defining the scope and complexity of this feature. You as maintainers know best what is the most likely to be useful to users, so I'm looking forward to hearing your thoughts!

sphinx-doc / sphinx

Feature request: Adding html_touch_icon setting. #7600