pyFDN 0.2.0__tar.gz → 0.4.0__tar.gz

pyfdn-0.4.0/AUTHORS.rst

@@ -0,0 +1,17 @@
+=======
+Credits
+=======
+
+
+Core Contributors
+-----------------
+
+* Sebastian J. Schlecht
+* Facundo Franchino
+* Jeremy Bai
+* Alma Hova
+* Cristóbal Andrade
+* Gloria Dal Santo
+* Bharadwaj Lakuduva Suresh Babu
+* Gian Marco De Bortoli
+* Kalyan Pandey

{pyfdn-0.2.0 → pyfdn-0.4.0}/CONTRIBUTING.rst

@@ -137,8 +137,35 @@ Building the Documentation
 Repository Index
 ----------------
 
-.. note::
-    This section will be filled out later with the goal structure of the repository.
+The repository separates the installable package, executable examples,
+documentation sources, and tests:
+
+* ``src/pyFDN/`` contains the library. The top-level ``__init__.py`` defines
+  the public API, while ``process.py``, ``build_io.py``, and ``presets.py``
+  provide the main processing and persistence entry points.
+* ``src/pyFDN/generate/`` contains feedback-matrix and FDN construction
+  algorithms, including the allpass and scattering-delay-network builders.
+* ``src/pyFDN/td/`` contains stateful block-processing operators and the
+  connectors (``Series``, ``Parallel``, ``Recursion``) that wire them into a
+  time-domain graph. ``process_fdn`` uses ``MatrixFIR`` for polynomial feedback
+  matrices; ``SOSBank`` implements per-delay-line filter cascades used for
+  frequency-dependent absorption.
+* ``src/pyFDN/eq/`` contains every EQ and absorption-filter design, while
+  ``src/pyFDN/translate/`` converts between delay state-space, transfer
+  function, pole-residue, impulse-response, and FLAMO representations.
+* ``src/pyFDN/train/`` contains the trainable FDN construction, the composable
+  losses in ``train/losses/``, and the optimization loop. ``src/pyFDN/auxiliary/`` holds shared analysis,
+  plotting, audio, delay, and numerical helpers.
+* ``examples/`` contains executable Marimo notebooks. Metadata at the top of
+  each ``example_*.py`` file drives the generated documentation gallery.
+* ``tests/`` mirrors the public feature areas with unit, regression, and
+  integration coverage; ``tests/reference/`` stores reference data and its
+  provenance notes.
+* ``docs/`` contains authored Sphinx pages and the scripts that generate API
+  stubs and galleries. Generated pages and HTML output are intentionally not
+  committed.
+* ``.github/`` contains the continuous-integration, packaging, and GitHub
+  Pages workflows.
 
 
 Testing Pipeline

pyfdn-0.4.0/HISTORY.rst

@@ -0,0 +1,91 @@
+=======
+History
+=======
+
+0.4.0 (2026-08-23)
+------------------
+
+* **Breaking:** replace ``train_fdn``'s ``mode`` string, and the ``target``,
+  ``criteria``, ``sparsity_alpha`` and ``mss_nfft`` arguments that went with
+  it, with a composed loss object. An objective is now written out --
+  ``FlatMagnitude() + 0.2 * Sparsity(param(model, "feedback"))`` -- and every
+  loss is a function of the impulse response, carried as a ``Response``, so
+  losses own their reference data and one objective can fit two different
+  references. ``pyFDN.train.objectives`` and ``build_objective`` are gone.
+* **Breaking:** collect every EQ design in ``pyFDN.eq`` (formerly
+  ``pyFDN.graphicEQ``) behind one ``EQDesign`` interface, with ``GraphicEQ``,
+  ``FirstOrderShelf`` and ``OnePole`` sharing a single implementation across
+  the numpy and torch backends.
+* **Breaking:** remove ``absorption_filters`` and ``absorption_to_rt``; the FIR
+  absorption path they served has no callers left.
+* **Breaking:** name the three filter hooks ``post_delay``, ``post_matrix`` and
+  ``post_output`` everywhere -- on ``FDNBuild``, in the FLAMO graph, in the
+  plots and in the JSON schema -- and add the slot for the third. The build
+  schema is version 2; version 1 files no longer load.
+* Fix colorless training on a lossless FDN, whose poles sit on the unit circle
+  and leave ``|H|`` unbounded. ``build_fdn`` now defaults ``alias_decay_db``
+  from ``rt`` (``LOSSLESS_ALIAS_DECAY_DB`` when ``rt`` is None) and
+  ``trainable_from_build`` threads it into every module, so a magnitude
+  objective sees a bounded response.
+* Train the decay: ``DecayFilter`` parametrizes the in-loop absorption filter
+  by reverberation time per band, so the loop stays contractive for every value
+  the parameter can take, and takes either one RT curve for the network or one
+  per delay line. ``OutputEQ`` trains the output filter outside the recursion,
+  the only part of an FDN that shapes the spectral envelope without touching
+  the decay. Both are passed as the ``post_delay`` and ``post_output`` hooks of
+  ``trainable_from_build``.
+* Add the losses that go with it: ``AsymmetricFlatMagnitude``,
+  ``FlatSpectrogram``, ``MatchEnergyDecay``, ``MatchCumulativeEnergy``,
+  ``MatchMagnitude``, ``MatchSpectrogram``, ``MatchMelSpectrogram``,
+  ``MatchImpulseResponse``, ``Energy``, ``Sparsity``, ``L1`` and ``L2``.
+* Resolve trainable parameters by name: ``param(model, "feedback")`` fails
+  where you write it with the list of available names, and ``params(model)``
+  enumerates them.
+* Export the FLAMO graph builders (``assemble_fdn_core``, ``wrap_fdn_shell``,
+  ``gain_module``, ``delay_module``, ``matrix_module``, ``fir_matrix_module``,
+  ``sos_filter_module``, ``hook_module``, ``DecayFilter``, ``OutputEQ``) from
+  the top-level namespace.
+* Make ``build_to_impz`` apply all three hooks, so it no longer rejects builds
+  that carry an output EQ, and make ``extract_build`` refuse a hook it cannot
+  bake rather than silently dropping it.
+* Add an example notebook that fits every parameter of an FDN, decay included,
+  to a measured concert-hall RIR, and document the loss rationale and
+  measurements in ``docs/training_losses.rst``.
+* Fix stereo orientation in ``labeled_audio``, which decoded a stereo render as
+  thousands of channels.
+* Check packaging metadata in CI and fail the documentation build on notebook
+  cell errors.
+
+0.3.0 (2026-08-17)
+------------------
+
+* **Breaking:** replace the ``pyFDN.dsp`` subpackage with ``pyFDN.td``. The
+  top-level ``FeedbackDelay``, ``FIRMatrixFilter`` and ``SOSFilterBank``
+  exports are gone; use ``pyFDN.td`` operators instead.
+* **Breaking:** ship the packaged colorless-FDN presets as JSON rather than
+  MATLAB ``.mat`` files.
+* Add ``pyFDN.td``, a time-domain block-based processing graph built on NumPy
+  alone (no torch, no FFT), with the ``Series``, ``Parallel`` and
+  ``Recursion`` connectors and stateful ``Gain``, ``Delay``, ``SOSBank``,
+  ``MatrixFIR``, ``MatrixConvolver`` and ``TimeVaryingMatrix`` operators.
+* Add ``load_fdn_build``, ``save_fdn_build``, ``fdn_build_from_dict`` and
+  ``fdn_build_to_dict`` for reading and writing FDN builds as JSON.
+* Add an FDN-to-FAUST example that compiles a pyFDN design with adac, and a
+  reverberation-enhancement example.
+* Improve the example gallery and stop tracking generated documentation in the
+  repository.
+* Test on Python 3.14 in CI and the documentation build.
+
+0.2.0 (2026-08-10)
+------------------
+
+* Package compact audio examples and predefined colorless-FDN coefficients so
+  browser-hosted tutorials work without repository-relative files.
+* Add public APIs for packaged audio, FDN presets, and paper references.
+* Add generated documentation galleries and wheel-content checks.
+* Keep decay-estimation dependencies optional for a smaller core installation.
+
+0.1.0 (2025-07-02)
+------------------
+
+* First release on PyPI.

{pyfdn-0.2.0 → pyfdn-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyFDN
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python library for Feedback Delay Networks
 Author: Sebastian J. Schlecht, Facundo Franchino, Jeremy Bai
 Maintainer: Facundo Franchino, Sebastian J. Schlecht
@@ -12,7 +12,7 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
@@ -25,14 +25,18 @@ Requires-Dist: flamo>=0.2.14
 Requires-Dist: flareverb
 Provides-Extra: examples
 Requires-Dist: marimo; extra == "examples"
+Requires-Dist: adac; extra == "examples"
 Requires-Dist: matplotlib>=3.5.0; extra == "examples"
 Requires-Dist: plotly>=5.0.0; extra == "examples"
 Requires-Dist: multislope>=0.1.1; extra == "examples"
+Requires-Dist: pyroomacoustics; extra == "examples"
 Provides-Extra: test
 Requires-Dist: marimo; extra == "test"
+Requires-Dist: adac; extra == "test"
 Requires-Dist: matplotlib>=3.5.0; extra == "test"
 Requires-Dist: plotly>=5.0.0; extra == "test"
 Requires-Dist: multislope>=0.1.1; extra == "test"
+Requires-Dist: pyroomacoustics; extra == "test"
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0.0; extra == "test"
 Requires-Dist: coverage>=7.0.0; extra == "test"
@@ -60,6 +64,8 @@ Requires-Dist: pandoc>=2.0; extra == "docs"
 Requires-Dist: plotly>=5.0.0; extra == "docs"
 Requires-Dist: matplotlib>=3.5.0; extra == "docs"
 Requires-Dist: multislope>=0.1.1; extra == "docs"
+Requires-Dist: pyroomacoustics; extra == "docs"
+Requires-Dist: adac; extra == "docs"
 Dynamic: license-file
 
 =====
@@ -93,6 +99,9 @@ Overview
 
 ``pyFDN`` provides building blocks for designing, simulating, and analysing Feedback Delay Networks (FDNs). The package focuses on reusable, tested helper functions that simplify typical FDN workflows such as creating orthogonal feedback matrices, designing loop filters, and inspecting pole locations. Using ``flamo`` as a dependency, ``pyFDN`` allows modular design of advanced FDN structure with DSP operations in time and frequency domain.
 
+The `pyFDN tutorial
+<https://artificial-audio.github.io/pyfdn-tutorial-2026/>`_ provides an introduction to the package.
+
 The source code is MIT-licensed. Small packaged tutorial resources retain the
 separate terms recorded in ``src/pyFDN/resources/ATTRIBUTION.md``; in
 particular, the Pori concert-hall impulse response is limited to
@@ -165,3 +174,12 @@ Or, inside an activated virtual environment::
 
 For linting and packaging helpers see ``Makefile`` (``make lint``/``make docs``)
 and ``tox.ini`` for multi-environment testing.
+
+
+Helpful links
+-------------
+
+* `List of papers on Feedback Delay Networks <https://github.com/gdalsanto/delay-network-reverbs>`_ .
+* `Multislope Estimation library <https://github.com/artificial-audio/multislope>`_ .
+* `FLAMO (An Open-Source Library for Frequency-Domain Differentiable Audio Processing) <https://github.com/gdalsanto/flamo>`_ .
+* `ADAC (Automatic Differentiable Audio Compilation) library <https://github.com/cucuwritescode/adac>`_ .

{pyfdn-0.2.0 → pyfdn-0.4.0}/README.rst

@@ -29,6 +29,9 @@ Overview
 
 ``pyFDN`` provides building blocks for designing, simulating, and analysing Feedback Delay Networks (FDNs). The package focuses on reusable, tested helper functions that simplify typical FDN workflows such as creating orthogonal feedback matrices, designing loop filters, and inspecting pole locations. Using ``flamo`` as a dependency, ``pyFDN`` allows modular design of advanced FDN structure with DSP operations in time and frequency domain.
 
+The `pyFDN tutorial
+<https://artificial-audio.github.io/pyfdn-tutorial-2026/>`_ provides an introduction to the package.
+
 The source code is MIT-licensed. Small packaged tutorial resources retain the
 separate terms recorded in ``src/pyFDN/resources/ATTRIBUTION.md``; in
 particular, the Pori concert-hall impulse response is limited to
@@ -101,3 +104,12 @@ Or, inside an activated virtual environment::
 
 For linting and packaging helpers see ``Makefile`` (``make lint``/``make docs``)
 and ``tox.ini`` for multi-environment testing.
+
+
+Helpful links
+-------------
+
+* `List of papers on Feedback Delay Networks <https://github.com/gdalsanto/delay-network-reverbs>`_ .
+* `Multislope Estimation library <https://github.com/artificial-audio/multislope>`_ .
+* `FLAMO (An Open-Source Library for Frequency-Domain Differentiable Audio Processing) <https://github.com/gdalsanto/flamo>`_ .
+* `ADAC (Automatic Differentiable Audio Compilation) library <https://github.com/cucuwritescode/adac>`_ .

pyfdn-0.4.0/docs/Makefile

@@ -0,0 +1,39 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+PYTHON        ?= python
+SPHINXOPTS    =
+SPHINXBUILD   ?= $(PYTHON) -msphinx
+SPHINXPROJ    = pyFDN
+SOURCEDIR     = .
+BUILDDIR      = _build
+SPHINXAPIDOC  ?= $(PYTHON) -msphinx.ext.apidoc
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile clean clean-generated generate-rst html
+
+# API stubs and autosummary pages are reproducible build inputs. Remove them
+# before every build so deleted or renamed public objects cannot leave stale
+# documentation behind.
+clean-generated:
+	$(RM) modules.rst pyFDN.rst pyFDN.*.rst
+	$(RM) -r generated
+
+generate-rst: clean-generated
+	$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)" ../src/pyFDN
+	$(PYTHON) patch_rst.py
+
+clean: clean-generated
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html: generate-rst
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

{pyfdn-0.2.0 → pyfdn-0.4.0}/docs/api_reference.rst

@@ -83,14 +83,9 @@ Acoustics & Absorption
    :toctree: generated/
    :nosignatures:
 
-   pyFDN.absorption_filters
-   pyFDN.first_order_absorption
-   pyFDN.first_order_shelving_eq
-   pyFDN.one_pole_absorption
    pyFDN.sos_gain_per_sample_curves
    pyFDN.echo_density
    pyFDN.edc
-   pyFDN.absorption_to_rt
    pyFDN.estimate_initial_level_bands
    pyFDN.estimate_rt_bands
    pyFDN.octave_bands
@@ -100,30 +95,58 @@ Acoustics & Absorption
    pyFDN.slope_amplitude_to_level
    pyFDN.slope_to_rt
 
-Graphic EQ
-----------
+EQ & Absorption Design (``pyFDN.eq``)
+--------------------------------------
+
+Three designs of the same two filters -- an FDN's in-loop absorption and its
+output EQ -- behind one interface. A design carries its own target and maps it
+to biquad sections in numpy or in torch from a single implementation, which is
+what a trainable :class:`pyFDN.DecayFilter` or :class:`pyFDN.OutputEQ` runs
+inside a training loop.
 
 .. autosummary::
    :toctree: generated/
    :nosignatures:
 
+   pyFDN.EQDesign
+   pyFDN.GraphicEQ
+   pyFDN.FirstOrderShelf
+   pyFDN.OnePole
    pyFDN.design_geq
+   pyFDN.geq_sos
+   pyFDN.geq_design_matrix
    pyFDN.graphic_eq
    pyFDN.absorption_geq
+   pyFDN.first_order_absorption
+   pyFDN.first_order_shelving_eq
+   pyFDN.one_pole_absorption
    pyFDN.probe_sos
    pyFDN.shelving_filter
    pyFDN.bandpass_filter
 
-DSP Components
---------------
+Time-Domain Graph (``pyFDN.td``)
+--------------------------------
+
+Stateful block-processing operators, wired into a graph by the connectors and
+rendered with ``.process(signal)``. See :mod:`pyFDN.td`.
 
 .. autosummary::
    :toctree: generated/
    :nosignatures:
 
-   pyFDN.FeedbackDelay
-   pyFDN.FIRMatrixFilter
-   pyFDN.SOSFilterBank
+   pyFDN.td.TimeOperator
+   pyFDN.td.Identity
+   pyFDN.td.Gain
+   pyFDN.td.Delay
+   pyFDN.td.AbsoluteValue
+   pyFDN.td.SOSBank
+   pyFDN.td.MatrixFIR
+   pyFDN.td.MatrixConvolver
+   pyFDN.td.TimeVaryingMatrix
+   pyFDN.td.RecursionState
+   pyFDN.td.Series
+   pyFDN.td.Parallel
+   pyFDN.td.Recursion
 
 Delay Utilities
 ---------------
@@ -138,6 +161,29 @@ Delay Utilities
    pyFDN.flamo_time_response
    pyFDN.flamo_freq_response
 
+Building a FLAMO Graph
+----------------------
+
+An FDN as FLAMO modules, assembled from numpy values. The three filter hooks --
+``post_delay`` inside the loop, ``post_matrix`` on the feedback path,
+``post_output`` on the wet signal -- are the same three
+:func:`pyFDN.process_fdn` takes, in the same positions and under the same names.
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   pyFDN.assemble_fdn_core
+   pyFDN.wrap_fdn_shell
+   pyFDN.gain_module
+   pyFDN.delay_module
+   pyFDN.matrix_module
+   pyFDN.fir_matrix_module
+   pyFDN.sos_filter_module
+   pyFDN.hook_module
+   pyFDN.DecayFilter
+   pyFDN.OutputEQ
+
 Polynomial & Matrix Maths
 --------------------------
 
@@ -188,8 +234,8 @@ General Utilities
    pyFDN.pole_boundaries
    pyFDN.skew
 
-Packaged Examples & References
-------------------------------
+Build Files, Packaged Examples & References
+--------------------------------------------
 
 .. autosummary::
    :toctree: generated/
@@ -200,6 +246,10 @@ Packaged Examples & References
    pyFDN.load_audio
    pyFDN.available_fdn_presets
    pyFDN.load_fdn_preset
+   pyFDN.fdn_build_to_dict
+   pyFDN.fdn_build_from_dict
+   pyFDN.save_fdn_build
+   pyFDN.load_fdn_build
    pyFDN.paper_reference
    pyFDN.paper_link
 
@@ -248,6 +298,38 @@ Training
    pyFDN.Trainable
    pyFDN.train_fdn
    pyFDN.TrainLog
+   pyFDN.LOSSLESS_ALIAS_DECAY_DB
+
+Training Objectives
+-------------------
+
+An objective is a weighted sum of losses, composed with ``+`` and ``*``. Losses
+on the impulse response read a :class:`pyFDN.Response`; losses on a model
+parameter take a :class:`pyFDN.ParamRef` from :func:`pyFDN.param`.
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   pyFDN.Response
+   pyFDN.model_response
+   pyFDN.param
+   pyFDN.params
+   pyFDN.ParamRef
+   pyFDN.Loss
+   pyFDN.FlatMagnitude
+   pyFDN.AsymmetricFlatMagnitude
+   pyFDN.FlatSpectrogram
+   pyFDN.MatchMagnitude
+   pyFDN.MatchSpectrogram
+   pyFDN.MatchMelSpectrogram
+   pyFDN.MatchImpulseResponse
+   pyFDN.MatchEnergyDecay
+   pyFDN.MatchCumulativeEnergy
+   pyFDN.Energy
+   pyFDN.Sparsity
+   pyFDN.L1
+   pyFDN.L2
 
 Plotting
 --------

{pyfdn-0.2.0 → pyfdn-0.4.0}/docs/audio_gallery.py

@@ -66,9 +66,9 @@ def render_gallery(examples: list[AudioExample]) -> str:
     lines = [
         ".. This file is generated by docs/audio_gallery.py. Do not edit it manually.",
         "",
-        "============",
+        "=============",
         "Audio Gallery",
-        "============",
+        "=============",
         "",
         "Audio examples demonstrating ``pyFDN``. The gallery is generated",
         "automatically from every packaged ``.wav`` file, grouped by resource category.",

{pyfdn-0.2.0 → pyfdn-0.4.0}/docs/conf.py

@@ -47,6 +47,11 @@ autosummary_imported_members = True
 # Napoleon settings (Google / NumPy docstrings)
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
+# Render "Attributes" sections as :ivar: fields instead of standalone
+# ``.. attribute::`` directives. Without this, every documented attribute is
+# registered twice (once by napoleon, once by autodoc's member scan) and Sphinx
+# warns about duplicate object descriptions.
+napoleon_use_ivar = True
 
 
 # Intersphinx mapping
@@ -114,7 +119,9 @@ latex_documents = [
 marimo_notebook_dir = "../examples"
 marimo_default_height = "800px"
 marimo_default_width = "100%"
-marimo_click_to_load = "overlay"  # Use overlay mode for better performance
+# ``True`` is rendered as the extension's overlay mode. Keep this a boolean;
+# sphinx-marimo declares the setting as such and Sphinx warns on string values.
+marimo_click_to_load = True
 marimo_load_button_text = "Load Interactive Notebook"
 
 # Build notebooks serially in-process. The export-mode override below patches the
@@ -141,6 +148,17 @@ marimo_cache_notebooks = False
 #
 # This patch lives in conf.py (our repo), so the installed sphinx-marimo package
 # stays pristine and deployment (RTD / GitHub Actions) needs no vendored changes.
+#
+# Cell errors are build failures: a notebook that raises still produces HTML,
+# with the traceback baked in where the output should be, so a broken example
+# reaches the published site looking like a rendered page. We record every
+# notebook whose export exited non-zero and fail the build at the end (see
+# ``setup`` below) instead of aborting on the first one, so a single run reports
+# all of them. Set ``PYFDN_DOCS_ALLOW_NOTEBOOK_ERRORS=1`` to downgrade this back
+# to a warning when you need a build out of a knowingly broken notebook.
+_marimo_export_failures: "list[tuple[str, str]]" = []
+
+
 def _patch_marimo_static_export():
     import subprocess
 
@@ -166,8 +184,8 @@ def _patch_marimo_static_export():
         # `html` (not `html-wasm`) executes the notebook server-side with the real
         # venv and embeds the outputs. marimo returns a non-zero exit code when any
         # cell raises during execution, but it still writes the HTML (with the error
-        # baked in), so we log a warning and keep going rather than aborting the
-        # whole docs build on one bad notebook.
+        # baked in), so we record the failure and keep going; the build-finished
+        # handler turns the collected failures into a build error.
         proc = subprocess.run(
             [
                 "marimo",
@@ -183,9 +201,10 @@ def _patch_marimo_static_export():
         )
         if proc.returncode != 0:
             print(
-                f"[conf.py] WARNING: '{relative_path}' had cell errors during static "
+                f"[conf.py] ERROR: '{relative_path}' had cell errors during static "
                 f"export (output still written):\n{proc.stderr.strip()}"
             )
+            _marimo_export_failures.append((str(relative_path), proc.stderr.strip()))
 
         return {
             "name": output_name,
@@ -198,3 +217,30 @@ def _patch_marimo_static_export():
 
 
 _patch_marimo_static_export()
+
+
+def _fail_on_marimo_export_errors(app, exception):
+    """Fail the build if any notebook raised while being exported."""
+    # The build already failed for another reason; don't mask it.
+    if exception is not None or not _marimo_export_failures:
+        return
+
+    report = "\n\n".join(
+        f"{path}:\n{stderr}" for path, stderr in _marimo_export_failures
+    )
+    if os.environ.get("PYFDN_DOCS_ALLOW_NOTEBOOK_ERRORS") == "1":
+        print(
+            f"[conf.py] WARNING: {len(_marimo_export_failures)} notebook(s) had cell "
+            f"errors; failing is disabled via PYFDN_DOCS_ALLOW_NOTEBOOK_ERRORS:\n{report}"
+        )
+        return
+
+    raise RuntimeError(
+        f"{len(_marimo_export_failures)} example notebook(s) raised during static "
+        f"export. The generated HTML contains the traceback instead of the intended "
+        f"output, so this must not be published:\n\n{report}"
+    )
+
+
+def setup(app):
+    app.connect("build-finished", _fail_on_marimo_export_errors)

{pyfdn-0.2.0 → pyfdn-0.4.0}/docs/example_gallery.py

@@ -60,27 +60,18 @@ def _plain_text(markdown: str) -> str:
     return text.strip()
 
 
-def _title_and_description(path: Path) -> tuple[str, str]:
+def _inferred_title(path: Path) -> str:
     blocks = _markdown_blocks(path)
     for block in blocks:
         lines = block.splitlines()
-        for index, line in enumerate(lines):
+        for line in lines:
             if not line.startswith("# "):
                 continue
             title = _plain_text(line[2:])
-            paragraphs = "\n".join(lines[index + 1 :]).strip().split("\n\n")
-            description = next(
-                (
-                    _plain_text(paragraph)
-                    for paragraph in paragraphs
-                    if paragraph.strip() and not paragraph.lstrip().startswith("#")
-                ),
-                "Open the rendered marimo notebook.",
-            )
-            return title, description
+            return title
 
     fallback = path.stem.removeprefix("example_").replace("_", " ").title()
-    return fallback, "Open the rendered marimo notebook."
+    return fallback
 
 
 def _metadata(path: Path) -> dict[str, str]:
@@ -93,25 +84,25 @@ def _metadata(path: Path) -> dict[str, str]:
     return metadata
 
 
-def _required_category(path: Path) -> str:
-    metadata = _metadata(path)
-    category = metadata.get("category")
-    if category:
-        return category
+def _required_metadata(path: Path, metadata: dict[str, str], key: str) -> str:
+    value = metadata.get(key)
+    if value:
+        return value
     relative = path.relative_to(PROJECT_ROOT)
-    raise ValueError(f"{relative} is missing a required '# gallery_category: ...' tag")
+    raise ValueError(f"{relative} is missing a required '# gallery_{key}: ...' tag")
 
 
 def discover_examples() -> list[Example]:
     examples = []
     for path in sorted(EXAMPLES_DIR.rglob("example_*.py")):
-        title, description = _title_and_description(path)
+        metadata = _metadata(path)
+        inferred_title = _inferred_title(path)
         examples.append(
             Example(
                 path,
-                title,
-                description,
-                _required_category(path),
+                metadata.get("title", inferred_title),
+                _required_metadata(path, metadata, "description"),
+                _required_metadata(path, metadata, "category"),
             )
         )
     return examples

{pyfdn-0.2.0 → pyfdn-0.4.0}/docs/index.rst

@@ -58,6 +58,7 @@ feedback matrices, designing loop filters, and inspecting pole locations.
    usage
    examples_gallery
    api_reference
+   training_losses
    modules
    contributing
    authors

pyfdn-0.4.0/docs/patch_rst.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Patch generated RST files to avoid duplicate object descriptions with api_reference."""
+
+import re
+from pathlib import Path
+
+DOCS = Path(__file__).parent
+
+# Replace pyFDN Module contents automodule with a link (avoids duplicates with api_reference)
+pyfdn_rst = DOCS / "pyFDN.rst"
+if pyfdn_rst.exists():
+    text = pyfdn_rst.read_text()
+    new = """Module contents
+---------------
+
+See :doc:`API Reference <api_reference>` for full documentation of all functions and classes."""
+    text = re.sub(
+        r"Module contents\n-+\n\n\.\. automodule:: pyFDN\n(   :[^\n]+\n)+",
+        new + "\n",
+        text,
+    )
+    pyfdn_rst.write_text(text)
+
+# Sub-package "Module contents" sections otherwise re-document every member
+# their __init__ re-exports. Keep the package docstring, but omit those members;
+# api_reference and the submodule sections remain the canonical targets.
+for package_rst in sorted(DOCS.glob("pyFDN.*.rst")):
+    package = package_rst.stem  # e.g. "pyFDN.graphicEQ"
+    text = package_rst.read_text()
+    pattern = rf"(\.\. automodule:: {re.escape(package)}\n(   :[^\n]+\n)+)"
+    match = re.search(pattern, text)
+    if match:
+        block = f".. automodule:: {package}\n   :no-index:\n   :no-members:\n"
+        text = text[: match.start()] + block + text[match.end() :]
+        package_rst.write_text(text)