update documentation (#27)

* use nox add nox to run test and mypy in isolated environment * use the complete python gitignore I faced some issue while building the nox, I think you can afford the full gitignore suggested by github * add mypy check in nox * use extra-require to build the test * add a mypy check in the github actions * reduce the number of tests linux test all the python version so windows and macos should only test 1 * forgot to reset pre-commit * reduce number of test again * build the doc with nox also drop requirement files * remove make files * use pydata-sphinx-theme for the doc * use copybutton * typo in icons names * refactoring * reduce readme to minimum * add a breaking change note * add a python version badge basd on the pypi classifiers * add a favicon to our doc * typo in project name * add an announcment banner * tune doc environment * Add pre-commit to dev dependencies * Small updates to README * Add lint session to nox * Remove print() * Update and expand RST docs Co-authored-by: tcmetzger <[email protected]>
tcmetzger · Jan 19, 2023 · 9d2c7a8 · 9d2c7a8
1 parent 7475c37
commit 9d2c7a8
Show file tree

Hide file tree

Showing 22 changed files with 435 additions and 281 deletions.
diff --git 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
@@ -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 `<head>` element:
+Based on this configuration, Sphinx will include the following favicon information in the HTML `<head>` element:
 
 ```html
 <link rel="icon" href="_static/icon.svg" type="image/svg+xml">
@@ -112,115 +66,11 @@ information in the HTML `<head>` element:
 <link rel="apple-touch-icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" sizes="180x180" type="image/png">
 ```
 
-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 `<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:
-
-```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 `<head>` of every HTML file:
-
-```html
-<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 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 `<head>` element:
-
-```html
-<link rel="icon" href="_static/icon.svg" type="image/svg+xml">
-<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">
-```
-
-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
diff --git a/docs-requirements.txt b/docs-requirements.txt
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/source/_static/android-chrome-192x192.png b/docs/source/_static/android-chrome-192x192.png
diff --git a/docs/source/_static/announcment.html b/docs/source/_static/announcment.html
@@ -0,0 +1,3 @@
+<p>
+	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 <code class="docutils literal notranslate"><span class="pre">conf.py</span></code> from <code class="docutils literal notranslate"><span class="pre">sphinx-favicon</span></code> to <code class="docutils literal notranslate"><span class="pre">sphinx_favicon</span></code>.
+</p>
diff --git a/docs/source/_static/apple-touch-icon.png b/docs/source/_static/apple-touch-icon.png
diff --git a/docs/source/_static/browserconfig.xml b/docs/source/_static/browserconfig.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/mstile-150x150.png"/>
+            <TileColor>#2d89ef</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>
diff --git a/docs/source/_static/custom.css 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;
+}
diff --git a/docs/source/_static/favicon-16x16.png b/docs/source/_static/favicon-16x16.png
diff --git a/docs/source/_static/favicon-32x32.png b/docs/source/_static/favicon-32x32.png
diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico
diff --git a/docs/source/_static/mstile-150x150.png b/docs/source/_static/mstile-150x150.png
diff --git a/docs/source/_static/safari-pinned-tab.svg b/docs/source/_static/safari-pinned-tab.svg