chore(docs): add references bib and improve

docs/source/conf.py

@@ -31,6 +31,7 @@
     "matplotlib.sphinxext.plot_directive",
     "myst_nb",
     "sphinxcontrib.apidoc",
+    "sphinxcontrib.bibtex",
     "sphinxext.opengraph",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
@@ -91,6 +92,10 @@
 
 # TODO: fix JS warnings about html-manager (wrong version?)
 
+# -- Bibtex
+
+bibtex_bibfiles = ["references.bib"]
+
 # Patch for Plotly from https://github.com/spatialaudio/nbsphinx/issues/128#issuecomment-1158712159
 
 html_js_files = [

docs/source/index.rst

@@ -14,3 +14,4 @@ DiffeRT: Differentiable Ray Tracing Toolbox for Radio Propagation
    :caption: Reference
 
    Public API: differt package<reference/differt>
+   references

docs/source/references.bib

@@ -0,0 +1,13 @@
+@inproceedings{mpt-eucap2023,
+  title        = {
+    Min-Path-Tracing: A Diffraction Aware Alternative to Image Method in Ray
+    Tracing
+  },
+  author       = {Eertmans, Jérome and Oestges, Claude and Jacques, Laurent},
+  year         = 2023,
+  booktitle    = {2023 17th European Conference on Antennas and Propagation (EuCAP)},
+  volume       = {},
+  number       = {},
+  pages        = {1--5},
+  doi          = {10.23919/EuCAP57121.2023.10132934}
+}

docs/source/references.rst

@@ -0,0 +1,4 @@
+References
+==========
+
+.. bibliography::

pyproject.toml

@@ -91,6 +91,7 @@ docs = [
   "sphinx-remove-toctrees>=0.0.3",
   "sphinxext-opengraph>=0.9.0",
   "sphinxcontrib-apidoc>=0.4.0",
+  "sphinxcontrib-bibtex>=2.5.0",
 ]
 github-action = [
   "jax[cpu]>=0.4.20",

python/differt/rt/utils.py

@@ -1,4 +1,30 @@
-"""Ray Tracing utilies."""
+"""
+Ray Tracing utilies.
+
+To generate a subset of all paths between two vertices, e.g.,
+a transmitter TX and a received RX, methods generate each
+path from a corresponding path candidate.
+
+A path candidate is simply a list of primitive indices
+to indicate with what primitive the path interact, and
+in what order. The latter indicates that any permutation
+of a given path candidate will result in another path.
+
+I.e., the path candidate ``[4, 7]`` indicates that
+the path first interacts with primitive ``4``, then
+primitive ``7``, while the path candidate ``[7, 4]``
+indicates a path interacting first with ``7`` then
+with ``4``.
+
+An empty path candidate indicates a direct path from
+TX or RX, also known as line of sight path.
+
+In general, interaction can be anything of the following:
+reflection, diffraction, refraction, etc. The utilities
+present in this module do not take care of the interaction type.
+
+You can read more about path candidates in :cite:`mpt-eucap2023`.
+"""
 from collections.abc import Iterator
 
 import jax.numpy as jnp