Sphinx Extension adding support for custom favicons
Project description
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'srelattribute, usually either the standard"icon"or a custom extension like"apple-touch-icon"sizes: a value for the favicon'ssizesattributehref: the absolute path to the favicon's image filetype: 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 addsrel="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
Built Distribution
Hashes for sphinx_favicon-0.1-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 4ca3e307ee6421a1aa6019f10529513497de88a707bd864021628d8192d51767 |
|
| MD5 | d5398e22aa1dd077658ba7999e611628 |
|
| BLAKE2b-256 | 207f0fb2c1e75c395b9c663846cb15903c5c99a8252b3beedc62bf1a3598f0a8 |
