sphinx-favicon

A Sphinx extension to add custom favicons

With sphinx-favicon, you can add custom favicons to your Sphinx html documentation quickly and easily.

You can define favicons directly in your conf.py, with different rel attributes such as "icon" or "apple-touch-icon" and any favicon size.

The sphinx-favicon extension gives you more flexibility than the standard favicon.ico supported by Sphinx. It provides a quick and easy way to add the most important favicon formats for different browsers and devices.

Installation

Use pip to install sphinx-favicon in your environment:

pip install sphinx-favicon

Usage

After installing sphinx-favicon, you can configure the extension directly in conf.py.

Currently, this extension requires absolute paths for your favicon files. Make sure you know the URL of all your favicon files, for example by adding the files to Sphinx' html_static_path.

First, add "sphinx-favicon" to the list of extensions:

extensions = [
    "sphinx-favicon",
]

Next, you have several options to define favicons:

Option A: Provide detailed metadata as a list of dicts

Use a list of dicts for maximum control over the favicons added to your html document. You can use the following parameters to define a favicon:

rel: a value for the favicon's rel attribute, usually either the standard "icon" or a custom extension like "apple-touch-icon"
sizes: a value for the favicon's sizes attribute
href: the absolute path to the favicon's image file
type: a value specifying the favicon's MIME type

For example:

favicons = [
    {
        "rel": "icon",
        "sizes": "16x16",
        "href": "https://secure.example.com/favicon/favicon-16x16.png",
        "type": "image/png",
    },
    {
        "rel": "icon",
        "sizes": "32x32",
        "href": "https://secure.example.com/favicon/favicon-32x32.png",
        "type": "image/png",
    },
    {
        "rel": "apple-touch-icon",
        "sizes": "180x180",
        "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
        "type": "image/png",
    },
]

Based on this configuration, Sphinx will include the following favicon information in the <head> of every HTML file:

<link rel="icon" href="https://secure.example.com/favicon/favicon-16x16.png" sizes="16x16" type="image/png">
<link rel="icon" href="https://secure.example.com/favicon/favicon-32x32.png" sizes="32x32" type="image/png">
<link rel="apple-touch-icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" sizes="180x180" type="image/png">

To make things easier for you, sphinx-favicon can also add some metadata to each favicon's <link> element automatically:

If you don't provide the "rel" argument, sphinx-favicon automatically adds rel="icon".
if you don't provide the "type" argument, sphinx-favicon automatically determines the MIME type based on the image's filename extension.
Currently, sphinx-favicon is not able to automatically read a file's size in pixels as required for the "size" argument. If you don't provide information about a favicon file's pixel size, the "size" argument will be omitted for that favicon image.

Therefore, the following simplified configuration generates the exact same HTML result as above:

favicons = [
    {
        "sizes": "16x16",
        "href": "https://secure.example.com/favicon/favicon-16x16.png",
    },
    {
        "sizes": "32x32",
        "href": "https://secure.example.com/favicon/favicon-32x32.png",
    },
    {
        "rel": "apple-touch-icon",
        "sizes": "180x180",
        "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
    },
]

Option B: Provide a single dict for just one favicon

If you want to add just one custom favicon, you can also use a simple dict in conf.py:

favicons = {
    "rel": "apple-touch-icon",
    "sizes": "180x180",
    "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
    }

Based on this configuration, Sphinx will include the following favicon information in the <head> of every HTML file:

<link rel="apple-touch-icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" sizes="180x180" type="image/png">

Option C: Provide a list of favicon URLs

The quickest way to add favicons is just adding a list of favicon URLs to conf.py.

favicons = [
    "https://secure.example.com/favicon/favicon-16x16.gif",
    "https://secure.example.com/favicon/favicon-32x32.png",
    "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
]

Based on this configuration, Sphinx will include the following favicon information in the <head> of every HTML file:

<link rel="icon" href="https://secure.example.com/favicon/favicon-16x16.gif" type="image/gif">
<link rel="icon" href="https://secure.example.com/favicon/favicon-32x32.png" type="image/png">
<link rel="icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" type="image/png">

Contribute

To contribute to this extension, please open an issue or make a pull request to the repository on GitHub.

Additional dependencies for development are listed in the file requirements.txt in the repository. All Python code should be formatted with Black.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-favicon-0.1.tar.gz (6.4 kB view details)

Uploaded Oct 4, 2021 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sphinx_favicon-0.1-py3-none-any.whl (5.4 kB view details)

Uploaded Oct 4, 2021 Python 3

File details

Details for the file sphinx-favicon-0.1.tar.gz.

File metadata

Download URL: sphinx-favicon-0.1.tar.gz
Upload date: Oct 4, 2021
Size: 6.4 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.1

File hashes

Hashes for sphinx-favicon-0.1.tar.gz
Algorithm	Hash digest
SHA256	`0429ceeb84d9200ecab5c21cb4ea94ea348549fab28881ebafdd55d6c9e1020f`
MD5	`530eb9d552f076c3478e59a7ed7c9b00`
BLAKE2b-256	`20173d349151975a9e14c6518fac4cef0ebc2de0e139bcd4352d4c373f0684d9`

See more details on using hashes here.

File details

Details for the file sphinx_favicon-0.1-py3-none-any.whl.

File metadata

Download URL: sphinx_favicon-0.1-py3-none-any.whl
Upload date: Oct 4, 2021
Size: 5.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.1

File hashes

Hashes for sphinx_favicon-0.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`4ca3e307ee6421a1aa6019f10529513497de88a707bd864021628d8192d51767`
MD5	`d5398e22aa1dd077658ba7999e611628`
BLAKE2b-256	`207f0fb2c1e75c395b9c663846cb15903c5c99a8252b3beedc62bf1a3598f0a8`