Add api_reference

Author: stevebachmeier

docs/nitpick-exceptions

@@ -0,0 +1,4 @@
+py:class InputData
+
+# external references that Sphinx cannot resolve
+py:class yaml.nodes.MappingNode

docs/source/api_reference/exceptions.rst

@@ -0,0 +1 @@
+.. automodule:: layered_config_tree.exceptions

docs/source/api_reference/index.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. automodule:: layered_config_tree
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs/source/api_reference/main.rst

@@ -0,0 +1 @@
+.. automodule:: layered_config_tree.main

docs/source/api_reference/utilities.rst

@@ -0,0 +1 @@
+.. automodule:: layered_config_tree.utilities

docs/source/conf.py

@@ -50,6 +50,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.doctest",
     "sphinx.ext.todo",
@@ -221,9 +222,9 @@
 nitpicky = True
 
 nitpick_ignore: list[tuple[str, str]] = []
-# for line in open("../nitpick-exceptions"):
-#     if line.strip() == "" or line.startswith("#"):
-#         continue
-#     dtype, target = line.split(None, 1)
-#     target = target.strip()
-#     nitpick_ignore.append((dtype, target))
+for line in open("../nitpick-exceptions"):
+    if line.strip() == "" or line.startswith("#"):
+        continue
+    dtype, target = line.split(None, 1)
+    target = target.strip()
+    nitpick_ignore.append((dtype, target))

docs/source/index.rst

@@ -5,3 +5,10 @@ Layered Config Tree Documentation
 Layered Config Tree is a configuration structure which supports cascading layers.
 
 TBD.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   api_reference/index
+

src/layered_config_tree/exceptions.py

@@ -1,3 +1,10 @@
+"""
+==========
+Exceptions
+==========
+
+"""
+
 from typing import Any
 
 

src/layered_config_tree/main.py

@@ -29,7 +29,6 @@
 
 from __future__ import annotations
 
-import warnings
 from collections.abc import Iterable
 from pathlib import Path
 from typing import Any
@@ -62,7 +61,7 @@ class ConfigNode:
 
     A :class:`ConfigNode` may only have a value set at each layer once.
     Attempts to set a value at the same layer multiple times will result in
-    a :class:`DuplicatedConfigurationError`.
+    a :class:`~layered_config_tree.exceptions.DuplicatedConfigurationError`.
 
     The :class:`ConfigNode` will record all values set and the source they
     are set from.  This sort of provenance with configuration data greatly
@@ -110,7 +109,6 @@ def freeze(self) -> None:
 
         This can be used to create a contract around when the configuration is
         modifiable.
-
         """
         self._frozen = True
 
@@ -158,7 +156,6 @@ def update(self, value: Any, layer: str | None, source: str | None) -> None:
         DuplicatedConfigurationError
             If a value has already been set at the provided layer or a value
             is already in the outermost layer and no layer has been provided.
-
         """
         if self._frozen:
             raise ConfigurationError(
@@ -193,8 +190,8 @@ def _get_value_with_source(self, layer: str | None) -> tuple[str | None, Any]:
 
         Returns
         -------
-        The (source, value) tuple at the specified layer or, if no layer is
-        specified, at the outermost (highest priority) layer.
+            The (source, value) tuple at the specified layer or, if no layer is
+            specified, at the outermost (highest priority) layer.
 
         Raises
         ------
@@ -247,6 +244,7 @@ class ConfigIterator:
     An iterator for a LayeredConfigTree object.
 
     This iterator is used to iterate over the keys of a LayeredConfigTree object.
+
     """
 
     def __init__(self, config_tree: LayeredConfigTree):
@@ -319,7 +317,6 @@ def freeze(self) -> None:
 
         This is useful for loading and then freezing configurations that
         should not be modified at runtime.
-
         """
         self.__dict__["_frozen"] = True
         for child in self.values():
@@ -353,7 +350,6 @@ def to_dict(self) -> dict[str, Any]:
         """Converts the LayeredConfigTree into a nested dictionary.
 
         All metadata is lost in this conversion.
-
         """
         result = {}
         for name, child in self.items():
@@ -386,9 +382,9 @@ def get(
 
         Returns
         -------
-        The value at the key or nested keys and at the requested layer (the outer, by default).
-        ``default_value`` (None, by default) is returned if the full key path *except
-        for the final key* exists at an *explicitly-requested* layer.
+            The value at the key or nested keys and at the requested layer (the outer, by default).
+            ``default_value`` (None, by default) is returned if the full key path *except
+            for the final key* exists at an *explicitly-requested* layer.
 
         Raises
         ------
@@ -421,8 +417,8 @@ def get_tree(self, keys: str | list[str]) -> LayeredConfigTree:
 
         Returns
         -------
-        The ``LayeredConfigTree`` located at the key or key path provided starting
-        from the outermost layer.
+            The ``LayeredConfigTree`` located at the key or key path provided starting
+            from the outermost layer.
 
         Raises
         ------
@@ -495,7 +491,6 @@ def update(
         DuplicatedConfigurationError
             If a value has already been set at the provided layer or a value
             is already in the outermost layer and no layer has been provided.
-
         """
         if data is not None:
             data_dict, source = self._coerce(data, source)
@@ -560,7 +555,6 @@ def _set_with_metadata(
         DuplicatedConfigurationError
             If a value has already been set at the provided layer or a value
             is already in the outermost layer and no layer has been provided.
-
         """
         if self._frozen:
             raise ConfigurationError(

src/layered_config_tree/utilities.py

@@ -61,22 +61,22 @@ class SafeLoader(yaml.SafeLoader):
     """A yaml.SafeLoader that restricts duplicate keys."""
 
     def construct_mapping(
-        self, node: yaml.MappingNode, deep: bool = False
+        self, node: yaml.nodes.MappingNode, deep: bool = False
     ) -> dict[Hashable, Any]:
         """Constructs the standard mapping after checking for duplicates.
 
         Raises
         ------
-        DuplicateKeysInYAMLError
+        DuplicatedConfigurationError
             If duplicate keys within the same level are detected in the YAML file
             being loaded.
 
         Notes
         -----
         A key is considered a duplicate only if it is the same as another key
-        _at the same level in the YAML_.
+        *at the same level in the YAML*.
 
-        This raises upon the _first_ duplicate key found; other duplicates may exist
+        This raises upon the *first* duplicate key found; other duplicates may exist
         (in which case a new error will be raised upon re-loading of the YAML file
         once the duplicate is resolved).
         """