NetherlandsForensicInstitute · akaIDIOT · Jun 25, 2025 · Jun 25, 2025 · Jan 31, 2025 · Jan 31, 2025
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -16,7 +16,7 @@ jobs:
           cache: true
           cache-dependency-path: 'pylock.toml'
       - name: Install check dependencies
-        run: pdm install --group check
+        run: pdm install --with check
       - name: Run checks
         run: pdm run check
   test:
@@ -33,6 +33,6 @@ jobs:
           cache: true
           cache-dependency-path: 'pylock.toml'
       - name: Install test dependencies
-        run: pdm install --group test
+        run: pdm install --with test
       - name: Run tests
         run: pdm run test
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,5 @@
-Changes
-=======
+Changelog
+=========
 
 development (main)
 ------------------

diff --git a/confidence/io.py b/confidence/io.py
@@ -67,7 +67,7 @@ def read_envvars(name: str, format: Format = YAML) -> Configuration:
     accessible in the resulting `Configuration` as
     ``c.spa_ce.key``, where ``c`` is the `Configuration` instance.
 
-    .. note::
+    !!! note
 
         An environment variable matching ``NAME_CONFIG_FILE`` (where the name
         part matches the *name* argument) is explicitly ignored here.
@@ -151,17 +151,25 @@ class Locality(IntEnum):
     variables.
     """
 
-    SYSTEM = 0  #: system-wide configuration locations
-    USER = 1  #: user-local configuration locations
-    APPLICATION = 2  #: application-local configuration locations (dependent on the current working directory)
-    ENVIRONMENT = 3  #: configuration from environment variables
+    SITE = 0
+    """System-wide configuration locations."""
+    SYSTEM = SITE
+
+    USER = 1
+    """User-local configuration locations."""
+
+    APPLICATION = 2
+    """Application-local configuration locations (dependent on the current working directory)."""
+
+    ENVIRONMENT = 3
+    """Configuration from environment variables."""
 
 
 Loadable = typing.Union[str, typing.Callable[[str, Format], Configuration]]
 
 
 _LOADERS: typing.Mapping[Locality, typing.Iterable[Loadable]] = {
-    Locality.SYSTEM: (
+    Locality.SITE: (
         # system-wide locations
         read_xdg_config_dirs,
         '/etc/{name}/{name}{suffix}',
@@ -194,22 +202,22 @@ def loaders(*specifiers: typing.Union[Locality, Loadable]) -> typing.Iterable[Lo
     """
     Generates loaders in the specified order.
 
-    Arguments can be `Locality` instances, producing the loader(s) available
-    for that locality, `str` instances (used as file path templates) or
-    `callable` s. These can be mixed:
-
-    .. code-block:: python
+    Arguments can be [Locality][confidence.Locality] instances, producing the
+    loader(s) available for that locality, `str` instances (used as file path
+    templates) or `callable` s. These can be mixed:
 
-        # define a load order using predefined user-local locations,
-        # an explicit path, a template and a user-defined function
-        load_order = loaders(Locality.user,
-                             '/etc/defaults/hard-coded.yaml',
-                             '/path/to/{name}{suffix}',
-                             my_loader)
+    ```python
+    # define a load order using predefined user-local locations,
+    # an explicit path, a template and a user-defined function
+    load_order = loaders(Locality.USER,
+                         '/etc/defaults/hard-coded.yaml',
+                         '/path/to/{name}{suffix}',
+                         my_loader)
 
-        # load configuration for name 'my-application' using the load order
-        # defined above
-        config = load_name('my-application', load_order=load_order)
+    # load configuration for name 'my-application' using the load order
+    # defined above
+    config = load_name('my-application', load_order=load_order)
+    ```
 
     :param specifiers: loader specifiers, see description
     :yields: configuration loaders in the specified order
@@ -225,7 +233,7 @@ def loaders(*specifiers: typing.Union[Locality, Loadable]) -> typing.Iterable[Lo
 
 DEFAULT_LOAD_ORDER = tuple(
     loaders(
-        Locality.SYSTEM,
+        Locality.SITE,
         Locality.USER,
         Locality.APPLICATION,
         Locality.ENVIRONMENT,

diff --git a/confidence/models.py b/confidence/models.py
@@ -9,8 +9,11 @@
 
 
 class Missing(Enum):
-    SILENT = 'silent'  #: return `NotConfigured` for unconfigured keys, avoiding errors
-    ERROR = 'error'  #: raise an `AttributeError` for unconfigured keys
+    SILENT = 'silent'
+    """Return `NotConfigured` for unconfigured keys, avoiding errors."""
+
+    ERROR = 'error'
+    """Raise an `AttributeError` for unconfigured keys."""
 
 
 # define a sentinel value to indicate there is no default value specified (None would be a valid default value)

diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: latest
+  jobs:
+    pre_install:
+      - pip install pdm
+      - pdm install --global --project . --with docs
+
+mkdocs:
+  configuration: docs/mkdocs.yaml
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1 @@
+../CHANGES.md
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,23 @@
+# Configure with `confidence` 😎
+
+Confidence does two things: it helps loading configuration options from file(s) and presents those options as a user-friendly object at runtime.
+Inspired by the way Python's own `pip` reads its configuration (try `pip config debug` if you're not familiar with `pip`'s configuration),
+confidence uses a similarly flexible, but deterministic approach to combining information from multiple configuration files.
+If that sounds awfully complicated, there's no requirement that you need to use anything that feels complicated.
+
+As a quick overview, confidence contains the following features:
+
+- a dict-like [`Configuration`][confidence.Configuration] object supporting attribute access to configured values;
+- customizable loading of multiple sources (files, environment variables, …) into a single object with deterministic precedence of those sources;
+- the ability to make and resolve references to values or entire namespaces.
+
+Want to jump right in?
+Check out [`confidence.load_name`][confidence.load_name] to get yourself a [`Configuration`][confidence.Configuration] as simple as this:
+
+```python
+# reading any files containing configuration for "myapp"
+config = confidence.load_name('myapp')
+# suppose myapp expects a dict… 
+# that's fine, a Configuration quacks just like it 😎
+myapp.run(config)
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml
@@ -0,0 +1,66 @@
+site_name: Configure with confidence 😎
+
+docs_dir: .
+site_dir: ../site
+repo_url: https://github.com/NetherlandsForensicInstitute/confidence/
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - toc.integrate
+  palette:
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      permalink: '#'
+
+plugins:
+- search
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_root_heading: true
+          show_root_members_full_path: true
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
+          show_source: false
+          show_bases: false
+          docstring_style: sphinx
+          separate_signature: true
+          signature_crossrefs: true
+
+nav:
+  - Home:
+    - index.md
+  - Usage:
+    - usage/loading.md
+    - usage/runtime.md
+    - usage/advanced.md
+  - Reference:
+    - reference/loading.md
+    - reference/objects.md
+    - reference/manipulation.md
+    - reference/exceptions.md
+  - Development:
+    - changelog.md
diff --git a/docs/recipes.rst b/docs/recipes.rst
diff --git a/docs/reference/exceptions.md b/docs/reference/exceptions.md
@@ -0,0 +1,17 @@
+# Exceptions
+
+::: confidence.ConfigurationError
+    options:
+        show_bases: true
+
+::: confidence.MergeConflictError
+    options:
+        show_bases: true
+
+::: confidence.ConfiguredReferenceError
+    options:
+        show_bases: true
+
+::: confidence.NotConfiguredError
+    options:
+        show_bases: true
diff --git a/docs/reference/loading.md b/docs/reference/loading.md
@@ -0,0 +1,15 @@
+# Loading functions
+
+::: confidence.load_name
+
+::: confidence.loadf
+
+::: confidence.loads
+
+::: confidence.loaders
+
+::: confidence.Locality
+
+::: confidence.DEFAULT_LOAD_ORDER
+
+::: confidence.Missing