refactor documentation (#35)

* refactor documentation * Refactor docs into chapters * Improve examples * Fix typos --------- Co-authored-by: tcmetzger <[email protected]>
tcmetzger · Feb 9, 2023 · ccd5a0c · ccd5a0c
1 parent fac4843
commit ccd5a0c
Show file tree

Hide file tree

Showing 10 changed files with 451 additions and 259 deletions.
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
 
 > **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`.
+> When moving from v0.2 to v0.3 the name of the extension was changed. Please update the name used in the extension list of your `conf.py` from `sphinx-favicon` to `sphinx_favicon`.
 
 **A Sphinx extension to add custom favicons**
 

diff --git a/docs/source/_static/announcment.html b/docs/source/_static/announcment.html
@@ -1,3 +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>
+	When moving from v0.2 to v0.3 the name of the extension was changed. Please update the name used in the extension 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/custom.css b/docs/source/_static/custom.css
@@ -18,4 +18,9 @@ div.highlight-console pre span.go::before {
   border-right: 1px solid var(--pst-color-text-base);
   margin-right: 0.5em;
   padding-right: 0.5em;
-}
+}
+
+.card-header-gray {
+  background-color: #c2c2c2 !important;
+  font-weight: bold;
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -9,13 +9,18 @@
 year = dt.datetime.now().year
 
 # -- Project information -------------------------------------------------------
-project = "sphinx-favicon"
+project = "Sphinx Favicon"
 copyright = f"{year}, Timo Metzger"
 author = "Timo Metzger"
 release = version
 
 # -- General configuration -----------------------------------------------------
-extensions = ["sphinx_favicon", "sphinx_copybutton"]
+extensions = [
+    "sphinx.ext.autosectionlabel",
+    "sphinx_favicon",
+    "sphinx_copybutton",
+    "sphinx_design",
+]
 source_suffix = [".rst", ".md"]
 templates_path = ["_templates"]
 exclude_patterns = ["Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
@@ -53,12 +58,7 @@
 # -- Option for favicons -------------------------------------------------------
 favicons = [
     # generic icons compatible with most browsers
-    {
-        # "rel": "icon",  # automatically set to "icon" if omitted
-        # "sizes": "32x32", # automatically set if the file can be read
-        # "type": "image/png",  # autogenerated from file type
-        "href": "favicon-32x32.png",
-    },
+    {"href": "favicon-32x32.png"},
     "favicon-16x16.png",
     {"rel": "shortcut icon", "sizes": "any", "href": "favicon.ico"},
     # chrome specific

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -0,0 +1,186 @@
+Configuration
+=============
+
+In the quickstart guide, you have used a simple list of favicons and **Sphinx Favicon**
+has automatically generated the corresponding HTML tags.
+
+This section will explain how to customize the configuration and use specific tags and
+attributes such as ``apple-touch-icon``.
+
+Defining favicons
+^^^^^^^^^^^^^^^^^
+
+Every favicon in **Sphinx Favicon** is defined as a dictionary of HTML attributes.
+
+For a single favicon, you can provide a single dictionary:
+
+.. code-block:: python
+
+   favicons = {"rel": "icon", "href": "icon.svg", "type": "image/svg+xml"}
+
+This will generate the following HTML tag:
+
+.. code-block:: html
+
+   <link rel="icon" href="_static/icon.svg" type="image/svg+xml">
+
+For multiple favicons, provide a list of dictionaries:
+
+.. code-block:: python
+
+   favicons = [
+      {"rel": "icon", "href": "icon.svg", "type": "image/svg+xml"},
+      {"rel": "icon", "sizes": "16x16", "href": "favicon-16x16.png", "type": "image/png"},
+      {"rel": "icon", "sizes": "32x32", "href": "favicon-32x32.png", "type": "image/png"},
+      {"rel": "apple-touch-icon", "sizes": "180x180", "href": "apple-touch-icon-180x180.png" "type": "image/png"}
+   ]
+
+This will generate the following HTML tags:
+
+.. code-block:: html
+
+   <link rel="icon" href="_static/icon.svg" type="image/svg+xml">
+   <link rel="icon" href="_static/favicon-16x16.png" sizes="16x16" type="image/png">
+   <link rel="icon" href="_static/favicon-32x32.png" sizes="32x32" type="image/png">
+   <link rel="apple-touch-icon" href="_static/apple-touch-icon-180x180.png" sizes="180x180" type="image/png">
+
+For any attributes that you don't explicitly set, **Sphinx Favicon** will infer the
+values from your provided input. For example: if you don't provide a ``type`` attribute,
+**Sphinx Favicon** will infer the type from the file extension. If you don't provide a
+``sizes`` attribute, **Sphinx Favicon** will attempt to read the pixel dimensions of the
+provided image.
+
+.. note::
+
+   If you provide a simple list (like in the quickstart guide), **Sphinx Favicon** will
+   automatically generate the dict behind the scenes.
+
+   Your list of favicons can also be a mixture of strings and dicts:
+
+   .. code-block:: python
+
+      favicons = [
+         "icon.svg",
+         "favicon-32x32.png",
+         {"rel": "apple-touch-icon", "href": "apple-touch-icon.png"},
+      ]
+
+   This will generate the following HTML tags:
+
+   .. code-block:: html
+
+      <link href="_static/icon.svg" rel="icon" type="image/svg+xml">
+      <link href="_static/favicon-32x32.png" sizes="32x32" rel="icon" type="image/png">
+      <link rel="apple-touch-icon" href="_static/_static/_static/apple-touch-icon.png" sizes="180x180" type="image/png">
+
+Customization
+^^^^^^^^^^^^^
+
+You can use any parameters to define your favicon as long as they are interpreted by
+browsers.
+
+The following attributes are the most commonly used ones:
+
+``href``: the image location
+############################
+
+You can define favicon images with the ``href`` attribute in two ways:
+
+Use an **absolute URL** for a favicon file. For example:
+
+.. code-block:: python
+
+   "href": "https://www.sphinx-doc.org/en/master/_static/favicon.svg"
+
+Use a **local static file** as a favicon. Make sure you place your local static
+favicon file(s) inside a directory listed in the Sphinx
+`"html_static_path" <https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path>`__.
+For example:
+
+.. code-block:: python
+
+   "href": "favicon.svg"
+
+.. note:: 
+
+   We continue to support the legacy ``static_file`` from v0.2 for local files.
+
+``sizes``: the image size
+#########################
+
+Use the ``sizes`` attribute as defined
+`here <https://html.spec.whatwg.org/multipage/semantics.html#attr-link-sizes>`__.
+
+For example:
+
+.. code-block:: python
+
+   "sizes": "16x16"
+
+**Sphinx Favicon** automatically computes a favicon's size if you don't provide a
+value for the ``sizes`` attribute (for BMP, GIF, JPEG, JPG and PNG files).
+
+``rel``: the favicon relation
+#############################
+
+Use the ``rel`` attribute to define the favicon relation. This can either be the
+standard `"icon" and "shortcut icon" <https://html.spec.whatwg.org/multipage/links.html#rel-icon>`__,
+or a custom relation like
+`"apple-touch-icon" <https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html>`__.
+
+For example:
+
+.. code-block:: python
+
+   "rel": "apple-touch-icon"
+
+If you don't provide a value for the ``rel`` attribute, **Sphinx Favicon** will
+automatically set ``rel="icon"``.
+
+``type``: the image MIME type
+#############################
+
+Use the ``type`` to define a favicon's MIME type as defined
+`here <https://html.spec.whatwg.org/multipage/semantics.html#attr-link-type>`__.
+
+For example:
+
+.. code-block:: python
+
+   "type": "image/svg+xml"
+
+If you don't provide a value for the ``rel`` attribute, **Sphinx Favicon** will
+automatically extract the MIME type from the provided image file  (for BMP, GIF, ICO,
+JPEG, JPG, PNG, and SVG files).
+
+``name``: specific to msapp icons
+#################################
+
+You also have the option to specify a ``name`` attribute. This is useful for
+``msapplication``-style favicons.
+
+If you use the ``name`` attribute, **Sphinx Favicon** will automatically set the
+``rel`` attribute to ``"meta"``.
+
+For example:
+
+.. code-block:: python
+
+   favicons = [
+      "mstile-150x150.png",
+      {"name": "msapplication-TileColor", "content": "#2d89ef"},
+      {"name": "theme-color", "content": "#ffffff"},
+   ]
+
+This will generate the following HTML tags:
+
+.. code-block:: html
+
+   <link href="_static/mstile-150x150.png" sizes="150x150" rel="icon" type="image/png">
+   <meta name="msapplication-TileColor" content="#2d89ef">
+   <meta name="theme-color" content="#ffffff">
+
+.. tip::
+
+   See the ``conf.py`` file for this documentation in the project's GitHub repository,
+   at https://github.com/tcmetzger/sphinx-favicon/blob/main/docs/source/conf.py
diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst
@@ -0,0 +1,107 @@
+Contribute
+==========
+
+Thank you for your help improving **Sphinx Favicon**!
+
+**Sphinx Favicon** uses `nox <https://nox.thea.codes/en/stable/>`__ 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}}
+
+For example: ``nox -s test`` or ``nox -s docs``.
+
+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
+
+See the following sections for more details.
+
+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 <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__.
+
+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 extension:
+
+.. code-block:: console
+
+   pip install -e .[dev]
+
+This will install the Sphinx Favicon library, together with two additional tools:
+-   `pre-commit <https://pre-commit.com>`__ for automatically enforcing code standards
+   and quality checks before commits.
+-   `nox <https://nox.thea.codes/en/stable/>`__, 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 <contributing-docs>` for more information on how to update the documentation.
+
+.. _contributing-docs:
+
+Contribute to the docs
+^^^^^^^^^^^^^^^^^^^^^^
+
+The documentation is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`__ and
+deployed to `Read the Docs <https://readthedocs.org/>`__.
+
+To build the documentation locally, use the following command:
+
+.. code-block:: console
+
+      nox -s docs
+
+For each pull request, the documentation is built and deployed to make it easier to
+review the changes in the PR. To access the docs build from a PR, click on the "Read
+the Docs" preview in the CI/CD jobs.