🗒️ Improve docs

docs/glossary.rst

@@ -1,6 +1,6 @@
-###########
+########
-Terminology
+Glossary
-###########
+########
 
 In this documentation, the following terms are used:
 

docs/goals.rst

@@ -0,0 +1,101 @@
+#############
+Project goals
+#############
+
+The project aims to accomplish multiple goals.
+
+
+Standards unification
+=====================
+
+The first goal is to allow easy integration of an application with multiple configuration standards, such as environment variables, dotenv files, and Docker Secrets files.
+
+:mod:`cfig` achieves it by allowing the developers of an application to specify where and how configuration values should be loaded from.
+
+.. code-block:: python
+
+    import cfig
+    import cfig.sources
+
+    config = cfig.Configuration(
+        sources=[
+            cfig.sources.EnvironmentSource(),
+            cfig.sources.EnvironmentSource(prefix="DEV" if __debug__ else "PROD"),
+            ...
+        ],
+    )
+
+
+Developer-friendliness
+======================
+
+The second goal is to provide a simple and Pythonic interface for developers to define and consume their configuration.
+
+:mod:`cfig` tries to achieve that by employing decorators and functions to create a declarative interface.
+
+.. code-block:: python
+
+    @config.required()
+    def SECRET_TOKEN(val: str) -> str:
+        """
+        The token used to encrypt messages. Keep it secret at all costs!
+        """
+        if val.startswith("v1"):
+            raise cfig.InvalidValueError("Old token, only v2 tokens are supported")
+        elif not val.startswith("v2"):
+            raise cfig.InvalidValueError("Unknown token version")
+        else:
+            return val
+
+.. code-block:: python
+
+    from .mycfig import SECRET_TOKEN
+
+    print(f"This is my secret token: {SECRET_TOKEN}. Don't mention it to anybody!")
+
+
+User-friendliness
+=================
+
+Another goal is to simplify deployments for system administrators, providing informative error messages and hints to the user configuring the application.
+
+:mod:`cfig` does that by providing a CLI displaying all possible configuration keys, their docstrings and their values.
+
+.. code-block:: python
+
+    if __name__ == "__main__":
+        config.cli()
+
+.. code-block:: console
+
+    $ python -m mycfig
+    ===== Configuration =====
+
+    SECRET_TOKEN → Required, but not set.
+    The token used to encrypt messages. Keep it secret at all costs!
+
+    ===== End =====
+    $ SECRET_TOKEN="v1:potato" python -m mycfig
+    ===== Configuration =====
+
+    SECRET_TOKEN → Old token, only v2 tokens are supported
+    The token used to encrypt messages. Keep it secret at all costs!
+
+    ===== End =====
+    $ SECRET_TOKEN="v2:qwertyasdf" python -m mycfig
+    ===== Configuration =====
+
+    SECRET_TOKEN = "v2:qwertyasdf"
+    The token used to encrypt messages. Keep it secret at all costs!
+
+    ===== End =====
+
+
+Developer hints
+===============
+
+The last goal of :mod:`cfig` is having complete and useful typing, so that developer tools may provide correct and useful type hints on configuration values.
+
+:mod:`cfig` currently does that, albeit using a few hacks to hide the true nature of :term:`proxies <proxy>`.
+
+.. image:: example-typing.png

docs/index.rst

@@ -5,54 +5,23 @@ cfig
 The :mod:`cfig` package provides a simple but powerful configuration manager for Python applications.
 
 
-Goals
+Table of contents
-=====
+=================
 
-A goal is to allow easy integration of an application with multiple configuration standards, such as environment
+.. toctree::
-variables, dotenv files, and Docker Secrets files.
 
-.. code-block:: python
+    installation
-
+    goals
-    @config.required()
+    reference
-    def SECRET_KEY(val: str) -> str:
+    glossary
-        "Secret string used to manage tokens."
-        return val
-
-Another goal is to provide informative error messages to the user who is configuring the application, so that they may
-understand what they are doing wrong and fix it immediately.
-
-.. code-block:: console
-
-    $ python -m cfig.sample
-    === Configuration ===
-
-    SECRET_KEY    → Required, but not set.
-    Secret string used to manage HTTP session tokens.
-
-    HIDDEN_STRING = 'amogus'
-    A string which may be provided to silently print a string to the console.
-
-Finally, the last goal is having useful typing for developers using :mod:`cfig`, allowing them to make full use of the
-features of their IDEs.
-
-.. image:: example-typing.png
 
 
 Example
 =======
 
-If you'd like to learn how to use :mod:`cfig` hands-on,
+If you'd like to learn how to use :mod:`cfig` hands-on, read `the source code of the cfig.sample module <https://github.com/Steffo99/cfig/tree/main/cfig/sample>`_!
-read `the source code of the cfig.sample module <https://github.com/Steffo99/cfig/tree/main/cfig/sample>`_!
 
 
-Pages of this documentation
-===========================
-
-.. toctree::
-
-    terminology
-    reference
-
 
 Other tables and links
 ======================

docs/installation.rst

@@ -0,0 +1,95 @@
+############
+Installation
+############
+
+You can install :mod:`cfig` in multiple ways!
+
+.. note::
+
+    Never install packages outside :mod:`venv`, unless you know very well what you're doing!
+
+
+From PyPI
+=========
+
+:mod:`cfig` is distributed through the `Python Package Index`_, and you can install it with your favourite dependency manager!
+
+.. _Python Package Index: https://pypi.org/
+
+
+Using pip
+---------
+
+You can install :mod:`cfig` through :mod:`pip`:
+
+.. code-block:: console
+
+    $ pip install cfig
+    Collecting cfig
+      Downloading cfig-0.2.1-py3-none-any.whl (12 kB)
+    Collecting lazy-object-proxy<2.0.0,>=1.7.1
+      Downloading lazy_object_proxy-1.7.1-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (62 kB)
+         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.3/62.3 KB 2.3 MB/s eta 0:00:00
+    Installing collected packages: lazy-object-proxy, cfig
+    Successfully installed cfig-0.2.1 lazy-object-proxy-1.7.1
+
+.. note::
+
+    If you're working on a project, remember to add it to your ``requirements.txt`` file!
+
+
+Using Poetry
+------------
+
+You can install :mod:`cfig` through :mod:`poetry`:
+
+.. code-block:: console
+
+    $ poetry add cfig
+    Using version ^0.2.1 for cfig
+
+    Updating dependencies
+    Resolving dependencies... (0.3s)
+
+    Writing lock file
+
+    Package operations: 2 installs, 0 updates, 0 removals
+
+      • Installing lazy-object-proxy (1.7.1)
+      • Installing cfig (0.2.1)
+
+
+From source
+===========
+
+If you have the source of :mod:`cfig`, you can install it from its own folder!
+
+
+Using PEP 518
+-------------
+
+Introduced with :pep:`518`, :mod:`pip` supports automatic build and installation:
+
+.. code-block:: console
+
+    $ cd cfig
+    $ pip install .
+
+
+For development
+===============
+
+If you want to contribute to :mod:`cfig`, you can use :mod:`poetry` to install the project in "development" mode in an isolated environment:
+
+.. code-block:: console
+
+    $ cd cfig
+    $ poetry install
+
+.. hint::
+
+    Setting ``virtualenvs.in-project`` to :data:`True` is recommended!
+
+    .. code-block:: console
+
+        $ poetry config virtualenvs.in-project true