docs: add section about configuraing paquo

Close #28

docs/source/configuration.rst

@@ -0,0 +1,107 @@
+Configuration
+=============
+
+.. note::
+    `Paquo` uses `dynaconf <https://www.dynaconf.com/>`_ for configuration management.
+
+`Paquo`\ s internal settings are configurable via a `.paquo.toml` file or via environment variables.
+If anything remains unclear after reading this section, please open an issue in the github repository!
+
+The .paquo.toml file
+--------------------
+
+To configure you `paquo` installation you can  place a `.paquo.toml` file in a spot where `paquo` can find it.
+To list all possible locations *(note: it's very many)* run:
+
+.. code-block:: console
+
+    user@computer:~$ python -m paquo config --search-tree
+
+This will output all search locations. These partially depend on where you run `paquo` from, which allows you
+to override certain settings for a project you're working on by having a custom `.paquo.toml` file in a
+project related location.
+
+To get a default template for the `.paquo.toml` run:
+
+.. code-block:: console
+
+    user@computer:~$ python -m paquo config --list --default
+
+This outputs the contents of the default paquo config toml:
+
+.. literalinclude:: ../../paquo/.paquo.defaults.toml
+    :language: toml
+    :linenos:
+
+.. tip::
+    If you want to store this in the directory `./config` run
+
+    .. code-block:: console
+
+        user@computer:~$ python -m paquo config -l -o `./config`
+
+    This will write a `.paquo.toml` file in the specified directory |:tada:|
+    (The directory must already exist)
+
+
+
+
+Environment variables
+---------------------
+
+All `paquo` settings can also be overridden by environment variables. Just prefix the particular
+setting with :code:`PAQUO_` and set the environment variable to what you want it to be.
+
+    PAQUO_LOG_LEVEL = :code:`WARNING`
+        valid: `DEBUG`, `INFO`, `WARNING`, `ERROR`
+
+    PAQUO_QUPATH_DIR = :code:`""`
+        if set will skip search and try to use qupath from this folder
+
+    PAQUO_QUPATH_SEARCH_DIRS
+        defaults to all default installation locations for QuPath this can be set to the folders that will be
+        searched for QuPath installations.
+
+    PAQUO_QUPATH_SEARCH_DIR_REGEX = :code:`"(?i)qupath.*"`
+        used to regex match qupath_dirs during search
+
+    PAQUO_QUPATH_SEARCH_CONDA = :code:`true`
+        should the conda installed QuPath be considered?
+
+    PAQUO_QUPATH_PREFER_CONDA = :code:`true`
+        should the conda installed QuPath be preferred over another locally installed QuPath
+
+    PAQUO_JAVA_OPTS = :code:`["-XX:MaxRAMPercentage=50",]`
+        a list of JVM options passed to the java virtual machine
+
+    PAQUO_MOCK_BACKEND = :code:`false`
+        an internal setting which allows building the docs without having qupath installed
+
+
+Verifying the config
+--------------------
+
+The easiest way to verify if your current configuration is correct is to run the command below,
+which will output something like the following to the console, and represents your current config:
+
+.. code-block:: console
+
+    user@computer:~$ python -m paquo config --list
+    # current paquo configuration
+    # ===========================
+    # format: TOML
+    log_level = "INFO"
+    qupath_dir = ""
+    qupath_search_dirs = [ "/usr/local",]
+    qupath_search_dir_regex = "(?i)qupath.*"
+    qupath_search_conda = true
+    qupath_prefer_conda = true
+    java_opts = [ "-XX:MaxRAMPercentage=50",]
+    mock_backend = false
+
+.. note::
+    Or if you want to go directly via `dynaconf` you can run
+
+    .. code-block:: console
+
+        user@computer:~$ dynaconf -i paquo.settings list

docs/source/index.rst

@@ -28,5 +28,6 @@ This page hosts the documentation for version "|version|".
    :caption: Contents:
 
    installation
+   configuration
    quickstart
    api