add documentation

docs/configuration.rst

@@ -3,7 +3,7 @@
 Configuration
 =============
 
-All configurations take place in your project's **conf.py** file.
+All root configurations take place in your project's :external+sphinx:ref:`conf.py file <build-config>`.
 
 Activation
 ----------
@@ -14,6 +14,13 @@ Add **sphinx_needs** to your extensions.
 
    extensions = ["sphinx_needs",]
 
+Available sphinx-needs options are then listed below, that can be added to your **conf.py** file.
+
+.. versionadded:: 4.1.0
+
+   Configuration can also be specified via a `toml file <https://toml.io>`__.
+   See :ref:`needs_from_toml` for more details.
+
 .. _config-warnings:
 
 Build Warnings
@@ -79,6 +86,41 @@ Options
 
 All configuration options starts with the prefix ``needs_`` for **Sphinx-Needs**.
 
+.. _needs_from_toml:
+
+needs_from_toml
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.1.0
+
+This configuration takes the (relative) path to a `toml file <https://toml.io>`__ which contains some or all of the needs configuration (configuration in the toml will override that in the :file:`conf.py`).
+
+.. code-block:: python
+
+   needs_from_toml = "ubproject.toml"
+
+Configuration in the toml can contain any of the options below, under a ``[needs]`` section,
+but with the ``needs_`` prefix removed.
+For example:
+
+.. code-block:: toml
+
+   [needs]
+   id_required = true
+   id_length = 3
+   types = [
+      {directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"},
+      {directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"},
+   ]
+
+To specify a different section name to read from in the toml file, use the ``needs_from_toml_section`` option:
+
+.. code-block:: python
+
+   needs_from_toml_section = ["tool", "needs"]
+
+.. caution:: Any configuration specifying relative paths in the toml file will be resolved relative to the directory containing the :file:`conf.py` file.
+
 needs_include_needs
 ~~~~~~~~~~~~~~~~~~~
 Set this option to False, if no needs should be documented inside the generated documentation.

sphinx_needs/config.py

@@ -307,15 +307,15 @@ def get_default(cls, name: str) -> Any:
             return _field.default_factory()
         return _field.default
 
-    from_toml: str | tuple[str, list[str]] | None = field(
-        default=None, metadata={"rebuild": "env", "types": (str, tuple, list)}
-    )
-    """Path to a TOML file to load configuration from.
-    
-    Optionally, a tuple of a path and a path to the section in the toml,
-    e.g. ``("path/to/file.toml", ["tools", "needs"])``,
-    by default the config is read from ``["needs"]``
-    """
+    from_toml: str | None = field(
+        default=None, metadata={"rebuild": "env", "types": (str, type(None))}
+    )
+    """Path to a TOML file to load configuration from."""
+
+    from_toml_section: list[str] = field(
+        default_factory=lambda: ["needs"], metadata={"rebuild": "env", "types": (list,)}
+    )
+    """Path to the section in the toml file to load configuration from."""
 
     types: list[NeedType] = field(
         default_factory=lambda: [

sphinx_needs/needs.py

@@ -369,26 +369,11 @@ def load_config_from_toml(app: Sphinx, config: Config) -> None:
     needs_config = NeedsSphinxConfig(config)
     if needs_config.from_toml is None:
         return
-    if isinstance(needs_config.from_toml, str):
-        toml_file = Path(needs_config.from_toml)
-        toml_path = ["needs"]
-    else:
-        try:
-            _toml_file, toml_path = needs_config.from_toml
-            assert isinstance(_toml_file, str), "First element must be a string"
-            assert isinstance(toml_path, (list, tuple)), "Second element must be a list"
-            toml_file = Path(_toml_file)
-        except Exception:
-            log_warning(
-                LOGGER,
-                "'needs_from_toml' is not a str or (str, list[str])",
-                "config",
-                None,
-            )
-            return
 
     # resolve relative to confdir
-    toml_file = Path(app.confdir, toml_file).resolve()
+    toml_file = Path(app.confdir, needs_config.from_toml).resolve()
+    toml_path = needs_config.from_toml_section
+
     if not toml_file.exists():
         log_warning(
             LOGGER,