docs: add usage documentation

docs/Makefile

@@ -0,0 +1,20 @@
+# 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     = .
+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)

docs/README.md

@@ -0,0 +1,13 @@
+# Documentation
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Run
+
+```
+sphinx-autobuild . _build/html
+```

docs/_static/css/style.css

@@ -0,0 +1,23 @@
+/* FONTS */
+@font-face {
+  font-family: "Cantarell var";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: normal;
+  font-named-instance: "Regular";
+  src: url("../fonts/Cantarell-VF.woff2") format("woff2"),
+    url("../fonts/Cantarell-VF.otf") format("opentype");
+}
+
+@font-face {
+  font-family: "Source Code Pro";
+  font-style: normal;
+  font-named-instance: "Regular";
+  src: url("../fonts/SourceCodePro-Regular.woff2") format("woff2"),
+    url("../fonts/SourceCodePro-Regular.otf") format("opentype");
+}
+
+html {
+  font-family: "Cantarell", sans-serif;
+  font-family: "Source Code Pro", monospace;
+}

docs/cli.rst

@@ -0,0 +1,188 @@
+.. highlight:: shell
+
+======
+⚙️ CLI
+======
+
+In version 0.4.0 we introduced an initial command-line interface, with a basic set of features from Gradience UI.
+
+How to launch CLI
+-----------------
+
+There are two different ways to launch CLI, one is for Flatpak version of Gradience, and another is for Gradience installed from other sources.
+
+Flatpak approach:
+-----------------
+
+If using Gradience as a Flatpak package, launch CLI with:
+
+.. code-block:: console
+
+    flatpak run --command=gradience-cli com.github.GradienceTeam.Gradience --help
+
+
+Alternative approach:
+---------------------
+
+Launch CLI with a dedicated command: `gradience-cli`
+
+CLI global help:
+----------------
+
+.. code-block:: console
+
+    usage: gradience-cli [-h] [-V] {presets,favorites,import,apply,download,monet,access-file,flatpak-overrides} ...
+
+    Gradience - Change the look of Adwaita, with ease
+
+    positional arguments:
+      {presets,favorites,import,apply,download,monet,access-file,flatpak-overrides}
+        presets             list installed presets
+        favorites           list favorite presets
+        import              import a preset
+        apply               apply a preset
+        download            download preset from a preset repository
+        monet               generate Material You preset from an image
+        access-file         allow or disallow Gradience to access a certain file or directory
+        flatpak-overrides   enable or disable Flatpak theming
+
+    options:
+      -h, --help            show this help message and exit
+      -V, --version         show program's version number and exit
+
+
+Available arguments
+-------------------
+
+Presets
+-------
+
+.. code-block:: console
+
+    usage: gradience-cli presets [-h] [-j]
+
+    options:
+      -h, --help  show this help message and exit
+      -j, --json  print out a result of this command directly in JSON format
+
+
+Favorites
+---------
+
+.. code-block:: console
+
+    usage: gradience-cli favorites [-h] [-a PRESET_NAME] [-r PRESET_NAME] [-j]
+
+    options:
+      -h, --help            show this help message and exit
+      -a PRESET_NAME, --add-preset PRESET_NAME
+                            add a preset to favorites
+      -r PRESET_NAME, --remove-preset PRESET_NAME
+                            remove a preset from favorites
+      -j, --json            print out a result of this command directly in JSON format
+
+
+Import
+------
+
+.. code-block:: console
+
+    usage: gradience-cli import [-h] -p PRESET_PATH
+
+    options:
+      -h, --help            show this help message and exit
+      -p PRESET_PATH, --preset-path PRESET_PATH
+                            absolute path to a preset file
+
+
+Apply
+-----
+
+.. code-block:: console
+
+    usage: gradience-cli apply [-h] (-n PRESET_NAME | -p PRESET_PATH) [--gtk {gtk4,gtk3,both}]
+
+    options:
+      -h, --help            show this help message and exit
+      -n PRESET_NAME, --preset-name PRESET_NAME
+                            display name for a preset
+      -p PRESET_PATH, --preset-path PRESET_PATH
+                            absolute path to a preset file
+      --gtk {gtk4,gtk3,both}
+                            types of applications you want to theme (default: gtk4)
+
+
+Download
+--------
+
+.. code-block:: console
+
+    usage: gradience-cli download [-h] -n PRESET_NAME
+
+    options:
+      -h, --help            show this help message and exit
+      -n PRESET_NAME, --preset-name PRESET_NAME
+                            name of a preset you want to get
+
+
+Monet
+-----
+
+.. code-block:: console
+
+    usage: gradience-cli monet [-h] -n PRESET_NAME -p IMAGE_PATH [--tone TONE] [--theme {light,dark}] [-j]
+
+    options:
+      -h, --help            show this help message and exit
+      -n PRESET_NAME, --preset-name PRESET_NAME
+                            name for a generated preset
+      -p IMAGE_PATH, --image-path IMAGE_PATH
+                            absolute path to image
+      --tone TONE           a tone for colors (default: 20)
+      --theme {light,dark}  choose whatever it should be a light or dark theme (default: light)
+      -j, --json            print out a result of this command directly in JSON format
+
+
+Access-file
+-----------
+
+.. code-block:: console
+
+    usage: gradience-cli access-file [-h] [-l] [-a PATH | -d PATH]
+
+    options:
+      -h, --help            show this help message and exit
+      -l, --list            list allowed directories and files
+      -a PATH, --allow PATH
+                            allow Gradience access to this file or directory
+      -d PATH, --disallow PATH
+                            disallow Gradience access to this file or directory
+
+
+Flatpak-overrides
+-----------------
+
+.. code-block:: console
+
+    usage: gradience-cli flatpak-overrides [-h] (-e {gtk4,gtk3,both} | -d {gtk4,gtk3,both})
+
+    options:
+      -h, --help            show this help message and exit
+      -e {gtk4,gtk3,both}, --enable-theming {gtk4,gtk3,both}
+                            enable overrides for Flatpak theming
+      -d {gtk4,gtk3,both}, --disable-theming {gtk4,gtk3,both}
+                            disable overrides for Flatpak theming
+
+
+Raw JSON output
+---------------
+
+Some commands contain local parameter `--json` to help developers in implementing interactions with Gradience. Currently it can only be used with a handful of available arguments, but there are plans to extend this feature to all arguments. This parameter when used with supported argument, will output argument result in JSON format.
+
+Example with `favorites` command:
+
+.. code-block:: console
+
+    $ gradience-cli favorites --json
+    {"favorites": ["Oblivion", "Peninsula", "Kate", "Yaru Dark", "Cobalt Dark", "Nord Dark"], "amount": 6}
+

docs/conf.py

@@ -0,0 +1,112 @@
+# 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
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Gradience'
+copyright = '2023, Gradience Team'
+author = 'Gradience Team'
+release = '0.4.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    "sphinxext.opengraph",
+    "sphinx_copybutton",
+    "myst_parser",
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# See https://pradyunsg.me/furo/ for the theme's documentation
+html_theme = 'furo'
+html_static_path = ['_static']
+html_css_files = ['css/style.css']
+html_logo = 'https://github.com/GradienceTeam/Design/raw/main/Pixels/Gradience Mini 4x (No Shadow).gif'
+
+#html_additional_pages = {
+#    "index": "index.html"
+#}
+#html_title = "Gradience"
+html_theme_options = {
+    "announcement": "This documentation is currently work in progress. Send your feedback or contribute!",
+    "source_repository": "https://github.com/GradienceTeam/Gradience",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "light_css_variables": {
+        "font-stack": "Cantarell var, sans-serif",
+        "font-stack--monospace": "Source Code Pro, monospace",
+    },
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/GradienceTeam/Gradience",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "Reddit",
+            "url": "https://reddit.com/r/gradiencecommunity",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 24 24" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><g><path fill="none" d="M0 0h24v24H0z"></path><path fill-rule="nonzero" d="M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10zm6.67-10a1.46 1.46 0 0 0-2.47-1 7.12 7.12 0 0 0-3.85-1.23L13 6.65l2.14.45a1 1 0 1 0 .13-.61L12.82 6a.31.31 0 0 0-.37.24l-.74 3.47a7.14 7.14 0 0 0-3.9 1.23 1.46 1.46 0 1 0-1.61 2.39 2.87 2.87 0 0 0 0 .44c0 2.24 2.61 4.06 5.83 4.06s5.83-1.82 5.83-4.06a2.87 2.87 0 0 0 0-.44 1.46 1.46 0 0 0 .81-1.33zm-10 1a1 1 0 1 1 2 0 1 1 0 0 1-2 0zm5.81 2.75a3.84 3.84 0 0 1-2.47.77 3.84 3.84 0 0 1-2.47-.77.27.27 0 0 1 .38-.38A3.27 3.27 0 0 0 12 16a3.28 3.28 0 0 0 2.09-.61.28.28 0 1 1 .39.4v-.04zm-.18-1.71a1 1 0 1 1 1-1 1 1 0 0 1-1.01 1.04l.01-.04z"></path></g></svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "Mastodon",
+            "url": "#",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M11.19 12.195c2.016-.24 3.77-1.475 3.99-2.603.348-1.778.32-4.339.32-4.339 0-3.47-2.286-4.488-2.286-4.488C12.062.238 10.083.017 8.027 0h-.05C5.92.017 3.942.238 2.79.765c0 0-2.285 1.017-2.285 4.488l-.002.662c-.004.64-.007 1.35.011 2.091.083 3.394.626 6.74 3.78 7.57 1.454.383 2.703.463 3.709.408 1.823-.1 2.847-.647 2.847-.647l-.06-1.317s-1.303.41-2.767.36c-1.45-.05-2.98-.156-3.215-1.928a3.614 3.614 0 0 1-.033-.496s1.424.346 3.228.428c1.103.05 2.137-.064 3.188-.189zm1.613-2.47H11.13v-4.08c0-.859-.364-1.295-1.091-1.295-.804 0-1.207.517-1.207 1.541v2.233H7.168V5.89c0-1.024-.403-1.541-1.207-1.541-.727 0-1.091.436-1.091 1.296v4.079H3.197V5.522c0-.859.22-1.541.66-2.046.456-.505 1.052-.764 1.793-.764.856 0 1.504.328 1.933.983L8 4.39l.417-.695c.429-.655 1.077-.983 1.934-.983.74 0 1.336.259 1.791.764.442.505.661 1.187.661 2.046v4.203z"></path></svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "Twitter",
+            "url": "#",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M5.026 15c6.038 0 9.341-5.003 9.341-9.334 0-.14 0-.282-.006-.422A6.685 6.685 0 0 0 16 3.542a6.658 6.658 0 0 1-1.889.518 3.301 3.301 0 0 0 1.447-1.817 6.533 6.533 0 0 1-2.087.793A3.286 3.286 0 0 0 7.875 6.03a9.325 9.325 0 0 1-6.767-3.429 3.289 3.289 0 0 0 1.018 4.382A3.323 3.323 0 0 1 .64 6.575v.045a3.288 3.288 0 0 0 2.632 3.218 3.203 3.203 0 0 1-.865.115 3.23 3.23 0 0 1-.614-.057 3.283 3.283 0 0 0 3.067 2.277A6.588 6.588 0 0 1 .78 13.58a6.32 6.32 0 0 1-.78-.045A9.344 9.344 0 0 0 5.026 15z"></path></svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "Discord",
+            "url": "#",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 640 512" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M524.531,69.836a1.5,1.5,0,0,0-.764-.7A485.065,485.065,0,0,0,404.081,32.03a1.816,1.816,0,0,0-1.923.91,337.461,337.461,0,0,0-14.9,30.6,447.848,447.848,0,0,0-134.426,0,309.541,309.541,0,0,0-15.135-30.6,1.89,1.89,0,0,0-1.924-.91A483.689,483.689,0,0,0,116.085,69.137a1.712,1.712,0,0,0-.788.676C39.068,183.651,18.186,294.69,28.43,404.354a2.016,2.016,0,0,0,.765,1.375A487.666,487.666,0,0,0,176.02,479.918a1.9,1.9,0,0,0,2.063-.676A348.2,348.2,0,0,0,208.12,430.4a1.86,1.86,0,0,0-1.019-2.588,321.173,321.173,0,0,1-45.868-21.853,1.885,1.885,0,0,1-.185-3.126c3.082-2.309,6.166-4.711,9.109-7.137a1.819,1.819,0,0,1,1.9-.256c96.229,43.917,200.41,43.917,295.5,0a1.812,1.812,0,0,1,1.924.233c2.944,2.426,6.027,4.851,9.132,7.16a1.884,1.884,0,0,1-.162,3.126,301.407,301.407,0,0,1-45.89,21.83,1.875,1.875,0,0,0-1,2.611,391.055,391.055,0,0,0,30.014,48.815,1.864,1.864,0,0,0,2.063.7A486.048,486.048,0,0,0,610.7,405.729a1.882,1.882,0,0,0,.765-1.352C623.729,277.594,590.933,167.465,524.531,69.836ZM222.491,337.58c-28.972,0-52.844-26.587-52.844-59.239S193.056,219.1,222.491,219.1c29.665,0,53.306,26.82,52.843,59.239C275.334,310.993,251.924,337.58,222.491,337.58Zm195.38,0c-28.971,0-52.843-26.587-52.843-59.239S388.437,219.1,417.871,219.1c29.667,0,53.307,26.82,52.844,59.239C470.715,310.993,447.538,337.58,417.871,337.58Z"></path></svg>
+            """,
+            "class": "",
+        },
+        {
+            "name": "Matrix",
+            "url": "#",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" role="img" viewBox="0 0 24 24" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><title></title><path d="M.632.55v22.9H2.28V24H0V0h2.28v.55zm7.043 7.26v1.157h.033c.309-.443.683-.784 1.117-1.024.433-.245.936-.365 1.5-.365.54 0 1.033.107 1.481.314.448.208.785.582 1.02 1.108.254-.374.6-.706 1.034-.992.434-.287.95-.43 1.546-.43.453 0 .872.056 1.26.167.388.11.716.286.993.53.276.245.489.559.646.951.152.392.23.863.23 1.417v5.728h-2.349V11.52c0-.286-.01-.559-.032-.812a1.755 1.755 0 0 0-.18-.66 1.106 1.106 0 0 0-.438-.448c-.194-.11-.457-.166-.785-.166-.332 0-.6.064-.803.189a1.38 1.38 0 0 0-.48.499 1.946 1.946 0 0 0-.231.696 5.56 5.56 0 0 0-.06.785v4.768h-2.35v-4.8c0-.254-.004-.503-.018-.752a2.074 2.074 0 0 0-.143-.688 1.052 1.052 0 0 0-.415-.503c-.194-.125-.476-.19-.854-.19-.111 0-.259.024-.439.074-.18.051-.36.143-.53.282-.171.138-.319.337-.439.595-.12.259-.18.6-.18 1.02v4.966H5.46V7.81zm15.693 15.64V.55H21.72V0H24v24h-2.28v-.55z"></path></svg>
+            """,
+            "class": "",
+        },
+    ],
+}
+
+# See https://github.com/wpilibsuite/sphinxext-opengraph for opengraph config