Fix duplicate label warning generated by autosectionlabel extension

docs/conf.py

@@ -158,4 +158,9 @@ def reset_mpl(gallery_conf, fname):
 ]
 plot_rcparams = {"axes.prop_cycle": cycler.cycler(color=["#228b18"])}
 
+# This is useful to prevent duplicate section label warnings
+autosectionlabel_prefix_document = True
+
+# Tell autosummary to generate the rst files
+# for the items in the summary.
 autosummary_generate = True

docs/getting_started/index.rst

@@ -44,7 +44,7 @@ To install all dependencies:
 Constructing Your First Spline
 ------------------------------
 
-**Note**: If you are unfamiliar with spline terminology, such as knots and control points, refer to our :ref:`theory introduction <Theory>`.
+**Note**: If you are unfamiliar with spline terminology, such as knots and control points, refer to our :ref:`theory introduction <theory/index:Theory>`.
 
 Constructing a spline with SplineBox is straightforward. You need to decide:
 
@@ -82,7 +82,7 @@ To shape the spline in `ndim` dimensions, you have three options:
 
       spline.fit(np.random.rand(100, ndim))
 
-   Learn more about how ``fit`` works in the theory section on :ref:`Data approximation` or by checking the API :meth:`splinebox.spline_curves.Spline.fit`.
+   Learn more about how ``fit`` works in the theory section on :ref:`theory/data_approximation:Data approximation` or by checking the API :meth:`splinebox.spline_curves.Spline.fit`.
 
 Evaluating/Sampling a Spline
 ----------------------------

docs/theory/index.rst

@@ -26,7 +26,7 @@ where
 One can intuitively think of :math:`r` being built by summing :math:`M` copies of :math:`\phi` centered at integer locations :math:`k=0,...,M-1`, each of them scaled by corresponding weights :math:`c[k]`.
 We refer to each :math:`t \in [k, k+1[, k=0,...,M-1` as **intervals**.
 
-We call junction points between the intervals knots :math:`n[k] = r(k)`. The relationship bewtween knots and control points is discussed on the page about the :ref:`Basis function`.
+We call junction points between the intervals knots :math:`n[k] = r(k)`. The relationship bewtween knots and control points is discussed on the page about the :ref:`theory/basis_function:Basis function`.
 
 The function :math:`r` can be made *periodic* by either :math:`M`-periodizing the sequence of :math:`\{ c[k] \}_{k=0,...,M-1}` such that :math:`c[0]=c[M]`, or by :math:`M`-periodizing :math:`\phi` and replacing it in :ref:`(1) <theory:eq:1>` by its periodized version
 

src/splinebox/basis_functions.py

@@ -141,7 +141,7 @@ class B1(BasisFunction):
     Basis function for a linear (:math:`1^{\text{st}}` order) polynomial basis spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Polynomial basis (B-spline)`
+    a plot of the function, refer to the :ref:`theory/polynomial:Polynomial basis (B-spline)`
     section in the documentation.
 
     The constructor does not require any arguments.
@@ -204,7 +204,7 @@ class B2(BasisFunction):
     Basis function for a quadratic (:math:`2^{\text{nd}}` order) polynomial basis spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Polynomial basis (B-spline)`
+    a plot of the function, refer to the :ref:`theory/polynomial:Polynomial basis (B-spline)`
     section in the documentation.
 
     The constructor does not require any arguments.
@@ -270,7 +270,7 @@ class B3(BasisFunction):
     Basis function for a cubic (:math:`3^{\text{rd}}` order) polynomial basis spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Polynomial basis (B-spline)`
+    a plot of the function, refer to the :ref:`theory/polynomial:Polynomial basis (B-spline)`
     section in the documentation.
 
     The constructor does not require any arguments.
@@ -408,7 +408,7 @@ class Exponential(BasisFunction):
     Basis function for an exponential spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Exponential basis`
+    a plot of the function, refer to the :ref:`theory/exponential:Exponential basis`
     section in the documentation.
 
     The constructor requires `M`, the number of knots in the spline, as an argument.
@@ -604,7 +604,7 @@ class CatmullRom(BasisFunction):
     Basis function for a Catmull Rom spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Catmull Rom basis`
+    a plot of the function, refer to the :ref:`theory/catmullrom:Catmull Rom basis`
     section in the documentation.
 
     The constructor does not require any arguments.
@@ -674,7 +674,7 @@ class CubicHermite(BasisFunction):
     Basis function for a cubic Hermite spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Cubic Hermite basis`
+    a plot of the function, refer to the :ref:`theory/cubichermite:Cubic Hermite basis`
     section in the documentation.
 
     The constructor does not require any arguments.
@@ -889,7 +889,7 @@ class ExponentialHermite(BasisFunction):
     Basis function for an exponential Hermite spline.
 
     For a detailed theoretical description, including the equation and
-    a plot of the function, refer to the :ref:`Exponential Hermite basis`
+    a plot of the function, refer to the :ref:`theory/exponentialhermite:Exponential Hermite basis`
     section in the documentation.
 
     The constructor requires `M`, the number of knots in the spline, as an argument.

src/splinebox/spline_curves.py

@@ -359,7 +359,7 @@ def fit(self, points, arc_length_parameterization=False):
         """
         Fit the provided points with the spline using
         least squares.
-        For details refer to :ref:`Data approximation`.
+        For details refer to :ref:`theory/data_approximation:Data approximation`.
 
         Parameters
         ----------
@@ -651,10 +651,10 @@ def normal(self, t, frame="bishop", initial_vector=None):
 
     def moving_frame(self, t, method="frenet", initial_vector=None):
         """
-        Compute a `moving frame`_ (local orthonormal coordinate system) along the spline.
+        Compute a moving frame (local orthonormal coordinate system) along the spline.
 
-        This method computes either the Frenet-Serret frame or the Bishop frame for
-        the spline. A moving frame consists of three orthonormal basis vectors at
+        This method computes either the Frenet-Serret frame or the Bishop frame [#bishop]_ for
+        the spline. A moving frame [#movingframe]_ consists of three orthonormal basis vectors at
         each point on the curve. The Frenet-Serret frame is derived from the curve's
         derivatives but may twist around the curve. The Bishop frame eliminates
         this twist, providing a zero-torsion alternative.
@@ -707,9 +707,9 @@ def moving_frame(self, t, method="frenet", initial_vector=None):
 
         References
         ----------
-        .. [1] Bishop, R. L. (1975). "There is More than One Way to Frame a Curve."
+        .. [#movingframe] `Moving frame <https://en.wikipedia.org/wiki/Moving_frame>`_ on Wikipedia.
+        .. [#bishop] Bishop, R. L. (1975). "There is More than One Way to Frame a Curve."
                American Mathematical Monthly, 82(3), 246-251.
-        .. _moving frame: https://en.wikipedia.org/wiki/Moving_frame
         """
         self._check_control_points()
         if self.control_points.ndim != 2 or self.control_points.shape[1] != 3: