diff --git a/.readthedocs.yml b/.readthedocs.yml index f058036..fc91d7a 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -15,11 +15,8 @@ build: sphinx: configuration: docs/source/conf.py -# If using Sphinx, optionally build your docs in additional formats such as PDF -# formats: -# - pdf - # Optionally declare the Python requirements required to build your docs python: - install: - - requirements: docs-requirements.txt + install: + - method: pip + path: .[doc] diff --git a/README.md b/README.md index 307e232..7b4622b 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,13 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Black badge](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![PyPI](https://img.shields.io/pypi/v/sphinx-favicon?logo=python&logoColor=white)](https://pypi.org/project/sphinx-favicon/) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-favicon?color=orange&logo=python&logoColor=white) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/tcmetzger/sphinx-favicon/basic-ci.yml?logo=github&logoColor=white) -[![Documentation Status](https://readthedocs.org/projects/sphinx-favicon/badge/?version=latest)](https://sphinx-favicon.readthedocs.io/en/latest/?badge=latest) +![Read the Docs (version)](https://img.shields.io/readthedocs/sphinx-favicon/latest?logo=readthedocs&logoColor=white) + +> **Note** +> **Updating from v0.2 to v0.3.** +> When moving from v0.2 to v0.3 the name of the extention was changed. Please update the name used in the extention list of your `conf.py` from `sphinx-favicon` to `sphinx_favicon`. **A Sphinx extension to add custom favicons** @@ -17,7 +22,7 @@ or [`"apple-touch-icon"`](https://developer.apple.com/library/archive/documentat any favicon size. The Sphinx Favicon extension gives you more flexibility than the [standard -`favicon.ico` supported by Sphinx](https://www.sphinx-doc.org/en/master/templating.html?highlight=favicon#favicon_url). It provides a quick and easy way to add the most +`favicon.ico` supported by Sphinx](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon). It provides a quick and easy way to add the most important favicon formats for different browsers and devices. ## Installation @@ -30,80 +35,29 @@ pip install sphinx-favicon ## Usage -After installing Sphinx Favicon, you can configure the extension directly in -`conf.py` (see [Configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html) -in the Sphinx documentation for more information about this file). - -There are two ways to include favicon files in your configuration: - -* Either use an **absolute URL** for a favicon file (beginning with `http://` or - `https://`). If you use an absolute URL, use the `"href"` parameter. See below - for examples. -* Or use a **local static file** as a favicon. Make sure you place your local - static favicon file(s) inside a directory listed in [Sphinx' `html_static_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path). If you use a relative path, use the `"static-file"` parameter. See below for - examples. - -To configure Sphinx Favicon, first add `"sphinx_favicon"` to the list of -extensions: +After installing **sphinx-favicon**, add it to your `conf.py` extension list: ```python -extensions = [ - "sphinx_favicon", -] +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"`](https://html.spec.whatwg.org/multipage/links.html#rel-icon) -or a custom extension like [`"apple-touch-icon"`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html) -* ``sizes``: a value for the [favicon's ``sizes`` attribute](https://html.spec.whatwg.org/multipage/semantics.html#attr-link-sizes) -* ``href``: the **absolute URL** to the favicon's image file (not required if you use the ``static-file`` parameter, see below) -* ``type``: a value specifying the [favicon's MIME type](https://html.spec.whatwg.org/multipage/semantics.html#attr-link-type) -* ``static-file``: the **local static file** corresponding to your icon's image. - Please notice this path should be relative to a directory listed in - [Sphinx' `html_static_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path) (usually `_static`). If you define both - ``static-file`` and ``href``, the value for ``href`` will be ignored. - -For example: +Then configure the favicon links using the `favicons` parameter (`html_static_path` is mandatory if you use relative path): ```python -html_static_path = ["_static"] # html_static_path is required if you use the "static-file" parameter +html_static_path = ["_static"] favicons = [ - { - "rel": "icon", - "static-file": "icon.svg", # => use `_static/icon.svg` - "type": "image/svg+xml", - }, - { - "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", - }, + {"static-file": "icon.svg"}, # => use `_static/icon.svg` + {"href": "https://secure.example.com/favicon/favicon-16x16.png"}, + {"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", - "type": "image/png", }, ] ``` -Based on this configuration, Sphinx will include the following favicon -information in the HTML `` element: +Based on this configuration, Sphinx will include the following favicon information in the HTML `` element: ```html @@ -112,115 +66,11 @@ information in the HTML `` element: ``` -Note that the relative path to the favicon's image file in the static directory -will be adjusted according to each html file's location. - -To make things easier for you, Sphinx Favicon can also add *some* metadata to -each favicon's `` 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: - -```python -html_static_path = ["_static"] - -favicons = [ - {"static-file": "icon.svg"}, # => use `_static/icon.svg` - { - "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`: - -```python -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 `` of every HTML file: - -```html - -``` - -### Option C: Provide a list of local favicon files or URLs - -The quickest way to add favicons is just adding a list of favicon URLs to -`conf.py`. - -```python -html_static_path = ["_static"] -favicons = [ - "icon.svg", # => `_static_/icon.svg` - "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 HTML `` element: - -```html - - - - -``` - -Please note that if your URLs don't start with `https://`, `http://` or `/`, -they will be considered a static file inside a directory listed in -[Sphinx' `html_static_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path). - -## Contribute - -To contribute to this extension, please open an issue or make a pull request to -the repository on GitHub. - -### Contributing to the codebase - -Additional dependencies for development are listed in the file -`dev-requirements.txt` in the repository. -Run `pip install -r dev-requirements.txt` to set up your environment, followed -by `pre-commit install`. -Using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) is -recommended. - -After installing the rev requirements, run ``pytest -vv`` to run tests. - -### Contributing to the docs - -The documentation uses [Sphinx](https://www.sphinx-doc.org/en/master/). +For more details and more advanced usage, please see the +[documentation](https://sphinx-favicon.readthedocs.io/en/stable). -To set up your environment to build the docs, run -`pip install -r docs-requirements.txt`. +## Contribution -To build the docs locally, enter the directory `docs` and run `make html`. +Contributions of any kind are welcome. Please see the +[contribution](https://sphinx-favicon.readthedocs.io/en/stable#Contribute) section of +our documntation for more information. diff --git a/dev-requirements.txt b/dev-requirements.txt deleted file mode 100644 index 8c51106..0000000 --- a/dev-requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ --e . -beautifulsoup4 -pre-commit -pytest -setuptools -sphinx diff --git a/docs-requirements.txt b/docs-requirements.txt deleted file mode 100644 index 7fce772..0000000 --- a/docs-requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -. -myst-parser -sphinx -sphinx_rtd_theme diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index dc1312a..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/_static/android-chrome-192x192.png b/docs/source/_static/android-chrome-192x192.png new file mode 100644 index 0000000..f319efa Binary files /dev/null and b/docs/source/_static/android-chrome-192x192.png differ diff --git a/docs/source/_static/announcment.html b/docs/source/_static/announcment.html new file mode 100644 index 0000000..cc5ceb8 --- /dev/null +++ b/docs/source/_static/announcment.html @@ -0,0 +1,3 @@ +

+ When moving from v0.2 to v0.3 the name of the extention was changed. Please update the name used in the extention list of your conf.py from sphinx-favicon to sphinx_favicon. +

\ No newline at end of file diff --git a/docs/source/_static/apple-touch-icon.png b/docs/source/_static/apple-touch-icon.png new file mode 100644 index 0000000..1adb434 Binary files /dev/null and b/docs/source/_static/apple-touch-icon.png differ diff --git a/docs/source/_static/browserconfig.xml b/docs/source/_static/browserconfig.xml new file mode 100644 index 0000000..a47e5a5 --- /dev/null +++ b/docs/source/_static/browserconfig.xml @@ -0,0 +1,9 @@ + + + + + + #2d89ef + + + diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..f66af7b --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,21 @@ +/* add dollar sign in console code-block */ +div.highlight-console pre span.go::before { + /*-webkit-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + -o-user-select: none; + user-select: none;*/ + content: "$"; + margin-right: 10px; + margin-left: 5px; +} + +/* make the footer inline */ +.footer-item { + display: inline-block; +} +.footer-item:not(:last-child) { + border-right: 1px solid var(--pst-color-text-base); + margin-right: 0.5em; + padding-right: 0.5em; +} \ No newline at end of file diff --git a/docs/source/_static/favicon-16x16.png b/docs/source/_static/favicon-16x16.png new file mode 100644 index 0000000..f008a6b Binary files /dev/null and b/docs/source/_static/favicon-16x16.png differ diff --git a/docs/source/_static/favicon-32x32.png b/docs/source/_static/favicon-32x32.png new file mode 100644 index 0000000..718485b Binary files /dev/null and b/docs/source/_static/favicon-32x32.png differ diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico new file mode 100644 index 0000000..d54fc8c Binary files /dev/null and b/docs/source/_static/favicon.ico differ diff --git a/docs/source/_static/mstile-150x150.png b/docs/source/_static/mstile-150x150.png new file mode 100644 index 0000000..10e1ca5 Binary files /dev/null and b/docs/source/_static/mstile-150x150.png differ diff --git a/docs/source/_static/safari-pinned-tab.svg b/docs/source/_static/safari-pinned-tab.svg new file mode 100644 index 0000000..547054c --- /dev/null +++ b/docs/source/_static/safari-pinned-tab.svg @@ -0,0 +1,33 @@ + + + + +Created by potrace 1.14, written by Peter Selinger 2001-2017 + + + + + + diff --git a/docs/source/_static/site.webmanifest b/docs/source/_static/site.webmanifest new file mode 100644 index 0000000..0e0e858 --- /dev/null +++ b/docs/source/_static/site.webmanifest @@ -0,0 +1,14 @@ +{ + "name": "", + "short_name": "", + "icons": [ + { + "src": "/android-chrome-192x192.png", + "sizes": "192x192", + "type": "image/png" + } + ], + "theme_color": "#ffffff", + "background_color": "#ffffff", + "display": "standalone" +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 8998530..14fba33 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,11 +1,6 @@ """Sphinx configuration file for sphinx-favicon documentation.""" -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- imports and read config ------------------------------------------------- +# -- imports and read config --------------------------------------------------- import datetime as dt import pkg_resources @@ -13,36 +8,76 @@ version = pkg_resources.require("sphinx-favicon")[0].version year = dt.datetime.now().year -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - +# -- Project information ------------------------------------------------------- project = "sphinx-favicon" copyright = f"{year}, Timo Metzger" author = "Timo Metzger" release = version -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "sphinx_rtd_theme", - "myst_parser", -] - +# -- General configuration ----------------------------------------------------- +extensions = ["sphinx_favicon", "sphinx_copybutton"] source_suffix = [".rst", ".md"] - templates_path = ["_templates"] -exclude_patterns = [] - +exclude_patterns = ["Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "sphinx_rtd_theme" +# -- Options for HTML output --------------------------------------------------- +html_theme = "pydata_sphinx_theme" html_static_path = ["_static"] +html_css_files = ["custom.css"] html_context = { "display_github": True, "github_user": "tcmetzger", "github_repo": "sphinx-favicon", "github_version": "main/docs/source/", } + +# -- Options for the html theme ------------------------------------------------ +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/tcmetzger/sphinx-favicon", + "icon": "fa-brands fa-github", + }, + { + "name": "PyPi", + "url": "https://pypi.org/project/sphinx-favicon/", + "icon": "fa-brands fa-python", + }, + ], + "logo": {"text": project}, + "use_edit_page_button": True, + "announcement": "https://raw.githubusercontent.com/12rambau/sphinx-favicon/doc/docs/source/_static/announcment.html", +} + +# -- Option for favicons ------------------------------------------------------- + +favicons = [ + { + "rel": "apple-touch-icon", + "size": "180x180", + "static-file": "apple-touch-icon.png", + }, + { + "rel": "icon", + "type": "image/png", + "size": "32x32", + "static-file": "favicon-32x32.png", + }, + { + "rel": "icon", + "type": "image/png", + "size": "16x16", + "static-file": "favicon-16x16.png", + }, + {"rel": "manifest", "static-file": "site.webmanifest"}, + {"rel": "mask-icon", "color": "#2d89ef", "static-file": "safari-pinned-tab.svg"}, + # { + # "name": "msapplication-TileColor", + # "content": "#2d89ef", + # }, + # { + # "name": "theme-color", + # "size": "#ffffff", + # }, +] diff --git a/docs/source/index.rst b/docs/source/index.rst index 3950f3b..d85cd17 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,18 +1,261 @@ Sphinx Favicon ============== -.. toctree:: - :maxdepth: 3 - :caption: Contents: +**A Sphinx extension to add custom favicons** -.. include:: ../../README.md - :parser: myst_parser.sphinx_ - :start-line: 8 +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: + +.. code-block:: console + + pip install sphinx-favicon + + +Usage +----- + +After installing **sphinx-favicon**, you can configure the extension directly in `conf.py`. There are two ways to include favicon files in your configuration: + +- Use an **absolute URL** for a favicon file (beginning with ``http://`` or ``https://``). If you use an absolute URL, use the ``href`` parameter. +- Use a **local static file** as a favicon. Make sure you place your local static favicon file(s) inside a directory listed in `Sphinx "html_static_path" `__. To use a relative path, use the ``static-file`` parameter. + +To configure **sphinx-favicon**, first add ``sphinx_favicon`` to the list of extensions: + +.. code-block:: python + + extensions = [ + #[...] + "sphinx_favicon", + ] + +Several options are then available to define favicons. They are listed in the following sections. + +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 any parameters to define your favicon as long as they are interpreted by browsers. Some specific keywords will change the HTML content: + +- ``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 as defined `here `__. It is computed on the fly if not set. +- ``type``: a value specifying the favicon's MIME type as defined `here `__. It is computed automatically if not set. +- ``href``: the **absolute URL** to the favicon's image file (not required if you use the ``static-file`` parameter) +- ``static-file``: the **local static file** to use as favicon. Please note that this path should be relative to a directory listed in `Sphinx "html_static_path" `__ (usually ``_static``). If you define both ``static-file`` and ``href``, the value for ``href`` will be ignored. +- ``name``: a value for the favicon's ``name``. Usually set for microsoft app metadata. If set, the tag will be set to ``meta``. + +**Example** + +.. code-block:: python + + html_static_path = ["_static"] # html_static_path is required if you use the "static-file" parameter + + favicons = [ + { + "rel": "icon", + "static-file": "icon.svg", # => use `_static/icon.svg` + "type": "image/svg+xml", + }, + { + "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 HTML `` element: + +.. code-block:: html + + + + + + +Note that the relative path to the favicon's image file in the static directory will be adjusted according to each html file's location. + +To make things easier for you, **sphinx-favicon** can also add *some* metadata to each favicon's `` element automatically: + +- If you don't provide the ``rel`` argument, **sphinx-favicon** automatically adds ``rel="icon"`` for ``link`` tags. +- if you don't provide the ``type`` argument, **sphinx-favicon** automatically determines the MIME type based on the image's filename extension. +- If not provided, **sphinx-favicon** will compute the ``sizes`` arguments automatically from the image provided in ``href``. + +Therefore, the following simplified configuration generates the exact same HTML result as above: + +.. code-block:: python + + html_static_path = ["_static"] + + favicons = [ + {"static-file": "icon.svg"}, # => use `_static/icon.svg` + {"href": "https://secure.example.com/favicon/favicon-16x16.png"}, + {"href": "https://secure.example.com/favicon/favicon-32x32.png"}, + { + "rel": "apple-touch-icon", + "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", + }, + ] + +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``: + +.. code-block:: python + + 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 ```` of every HTML file: + +.. code-block:: html + + + +Provide a list of local favicon files or URLs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The quickest way to add favicons is to just add a list of favicon URLs to ``conf.py``. + +.. code-block:: python + + html_static_path = ["_static"] + favicons = [ + "icon.svg", # => `_static_/icon.svg` + "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 HTML ```` element: + +.. code-block:: html + + + + + + +Please note that if your URLs don't start with ``https://``, ``http://`` or ``/``, they will be considered a static file inside a directory listed in `Sphinx "html_static_path" `__. + +Contribute +---------- + +Thank you for your help improving **sphinx-favicon**! + +**sphinx-favicon** uses `nox `__ to automate several +development-related tasks. +Currently, the project uses four automation processes (called sessions) in ``noxfile.py``: + +- ``mypy``: to perform a mypy check on the lib; +- ``test``: to run the test with pytest; +- ``docs``: to build the documentation in the ``build`` folder; +- ``lint``: to run the pre-commits in an isolated environment + +Every nox session is run in its own virtual environment, and the dependencies are +installed automatically. + +To run a specific nox automation process, use the following command: + +.. code-block:: console + + nox -s {{session name}} + +Workflow for contributing changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We follow a typical GitHub workflow of: + +- Create a personal fork of this repo +- Create a branch +- Open a pull request +- Fix findings of various linters and checks +- Work through code review + +For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR. To access this, click on the Read the Docs preview in the CI/CD jobs. + +.. note:: + + The sections below cover the steps to do this in more detail. + +Clone the repository +^^^^^^^^^^^^^^^^^^^^ + +First off, you'll need your own copy of the **sphinx-favicon** codebase. You can clone it for local development like so: + +Fork the repository so you have your own copy on GitHub. See the `GitHub forking guide for more information `__. Then, clone the repository locally so that you have a local copy to work on: + +.. code-block:: console + + git clone https://github.com/{{ YOUR USERNAME }}/sphinx-favicon + cd sphinx-favicon + +Then install the development version of the extention: + +.. code-block:: console + + pip install -e .[dev] + +This will install the sphinx-favicon library, together with two extra tools: +- `pre-commit `__ for automatically enforcing code standards and quality checks before commits. +- `nox `__, for automating common development tasks. + +Lastly, activate the pre-commit hooks by running: + +.. code-block:: console + + pre-commit install + +This will install the necessary dependencies to run pre-commit every time you make a commit with Git. + +Contribute to the codebase +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Any larger updates to the codebase should include tests and documentation. +The tests are located in the ``tests`` folder, and the documentation is located in the ``docs`` folder. + +To run the tests locally, use the following command: + +.. code-block:: console + + nox -s test + +See :ref:`below ` for more information on how to update the documentation. + +.. _contributing-docs: + +Contribute to the docs +^^^^^^^^^^^^^^^^^^^^^^ + +The documentation is built using `Sphinx `__ and +deployed to `Read the Docs `__. + +To build the documentation locally, use the following command: + +.. code-block:: console + + nox -s docs -.. Indices and tables -.. ================== -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` diff --git a/noxfile.py b/noxfile.py index 6083f39..eeaf51b 100644 --- a/noxfile.py +++ b/noxfile.py @@ -3,7 +3,7 @@ import nox -@nox.session(python=["3.7", "3.8", "3.9"], reuse_venv=True) +@nox.session(reuse_venv=True) def test(session): """Apply the tests on the lib.""" session.install(".[test]") @@ -23,3 +23,17 @@ def mypy(session): "--non-interactive", *test_files, ) + + +@nox.session(name="docs", reuse_venv=True) +def docs(session): + """Build the docs.""" + session.install(".[doc]") + session.run("sphinx-build", "-b=html", "docs/source", "docs/build/html") + + +@nox.session(reuse_venv=True) +def lint(session): + """Run pre-commit linting checks.""" + session.install(".[test]") + session.run("pre-commit", "run", "--all-files", external=True) diff --git a/setup.cfg b/setup.cfg index d32df74..c6dbe84 100644 --- a/setup.cfg +++ b/setup.cfg @@ -42,7 +42,8 @@ test = beautifulsoup4 dev = nox + pre-commit doc = - sphinx + sphinx<6 pydata-sphinx-theme - + sphinx-copybutton diff --git a/sphinx_favicon/__init__.py b/sphinx_favicon/__init__.py index 95b7952..2810413 100644 --- a/sphinx_favicon/__init__.py +++ b/sphinx_favicon/__init__.py @@ -74,7 +74,6 @@ def generate_meta(favicon: Dict[str, str]) -> str: # build the html element parameters = [f'{k}="{v}"' for k, v in favicon.items()] html_element = f" <{tag} {' '.join(parameters)}>" - print(html_element) return html_element