Fix issues in the documentation (#146)

.readthedocs.yaml

@@ -14,6 +14,7 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/source/conf.py
+   fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF
 formats:

lasy/laser.py

@@ -49,6 +49,7 @@ class Laser:
     >>> import matplotlib.pyplot as plt
     >>> from lasy.laser import Laser
     >>> from lasy.profiles.gaussian_profile import GaussianProfile
+    >>> from lasy.utils.laser_utils import get_full_field
     >>> # Create profile.
     >>> profile = GaussianProfile(
     ...     wavelength=0.6e-6,  # m
@@ -72,10 +73,10 @@ class Laser:
     >>> fig, axes = plt.subplots(1, n_steps, sharey=True)
     >>> for step in range(n_steps):
     >>>     laser.propagate(propagate_step)
-    >>>     E_rt, extent = laser.get_full_field()
-    >>>     extent[:2] *= 1e6
-    >>>     extent[2:] *= 1e12
-    >>>     rmin, rmax, tmin, tmax = extent
+    >>>     E_rt, extent = get_full_field(laser)
+    >>>     extent[2:] *= 1e6
+    >>>     extent[:2] *= 1e12
+    >>>     tmin, tmax, rmin, rmax = extent
     >>>     vmax = np.abs(E_rt).max()
     >>>     axes[step].imshow(
     ...         E_rt,

lasy/profiles/combined_profile.py

@@ -12,8 +12,8 @@ class CombinedLongitudinalTransverseProfile(Profile):
 
     .. math::
 
-        E_u(\\boldsymbol{x}_\\perp,t) = Re\\left[ E_0\\, \\mathcal{T}(x, y)
-        \\times \\mathcal{L}(t) e^{-i\\omega_0 t} \\times p_u \\right]
+        E_u(\boldsymbol{x}_\perp,t) = Re\left[ E_0\, \mathcal{T}(x, y)
+        \times \mathcal{L}(t) e^{-i\omega_0 t} \times p_u \right]
 
     where :math:`u` is either :math:`x` or :math:`y`, :math:`p_u` is
     the polarization vector, :math:`Re` represent the real part.
@@ -22,9 +22,9 @@ class CombinedLongitudinalTransverseProfile(Profile):
     Parameters
     ----------
     wavelength : float (in meter)
-        The main laser wavelength :math:`\\lambda_0` of the laser, which
-        defines :math:`\\omega_0` in the above formula, according to
-        :math:`\\omega_0 = 2\\pi c/\\lambda_0`.
+        The main laser wavelength :math:`\lambda_0` of the laser, which
+        defines :math:`\omega_0` in the above formula, according to
+        :math:`\omega_0 = 2\pi c/\lambda_0`.
 
     pol : list of 2 complex numbers (dimensionless)
         Polarization vector. It corresponds to :math:`p_u` in the above
@@ -39,11 +39,11 @@ class CombinedLongitudinalTransverseProfile(Profile):
 
     long_profile : an instance of `lasy`'s :class:LongitudinalProfile
         Defines the longitudinal envelope of the laser, i.e. the
-        function :math:`\\mathcal{L}(t)` in the above formula.
+        function :math:`\mathcal{L}(t)` in the above formula.
 
     transverse_profile : an instance of `lasy`'s :class:TransverseProfile
         Defines the transverse envelope of the laser, i.e. the
-        function :math:`\\mathcal{T}(x, y)` in the above formula.
+        function :math:`\mathcal{T}(x, y)` in the above formula.
     """
 
     def __init__(self, wavelength, pol, laser_energy, long_profile, trans_profile):

lasy/profiles/gaussian_profile.py

@@ -11,23 +11,23 @@ class GaussianProfile(CombinedLongitudinalTransverseProfile):
 
     .. math::
 
-        E_u(\\boldsymbol{x}_\\perp,t) = Re\\left[ E_0\\,
-        \\exp\\left( -\\frac{\\boldsymbol{x}_\\perp^2}{w_0^2}
-        - \\frac{(t-t_{peak})^2}{\\tau^2} -i\\omega_0(t-t_{peak})
-        + i\\phi_{cep}\\right) \\times p_u \\right]
+        E_u(\boldsymbol{x}_\perp,t) = Re\left[ E_0\,
+        \exp\left( -\frac{\boldsymbol{x}_\perp^2}{w_0^2}
+        - \frac{(t-t_{peak})^2}{\tau^2} -i\omega_0(t-t_{peak})
+        + i\phi_{cep}\right) \times p_u \right]
 
     where :math:`u` is either :math:`x` or :math:`y`, :math:`p_u` is
     the polarization vector, :math:`Re` represent the real part, and
-    :math:`\\boldsymbol{x}_\\perp` is the transverse coordinate (orthogonal
+    :math:`\boldsymbol{x}_\perp` is the transverse coordinate (orthogonal
     to the propagation direction). The other parameters in this formula
     are defined below.
 
     Parameters
     ----------
     wavelength : float (in meter)
-        The main laser wavelength :math:`\\lambda_0` of the laser, which
-        defines :math:`\\omega_0` in the above formula, according to
-        :math:`\\omega_0 = 2\\pi c/\\lambda_0`.
+        The main laser wavelength :math:`\lambda_0` of the laser, which
+        defines :math:`\omega_0` in the above formula, according to
+        :math:`\omega_0 = 2\pi c/\lambda_0`.
 
     pol : list of 2 complex numbers (dimensionless)
         Polarization vector. It corresponds to :math:`p_u` in the above
@@ -44,17 +44,17 @@ class GaussianProfile(CombinedLongitudinalTransverseProfile):
         The waist of the laser pulse, i.e. :math:`w_0` in the above formula.
 
     tau : float (in second)
-        The duration of the laser pulse, i.e. :math:`\\tau` in the above
-        formula. Note that :math:`\\tau = \\tau_{FWHM}/\\sqrt{2\\log(2)}`,
-        where :math:`\\tau_{FWHM}` is the Full-Width-Half-Maximum duration
+        The duration of the laser pulse, i.e. :math:`\tau` in the above
+        formula. Note that :math:`\tau = \tau_{FWHM}/\sqrt{2\log(2)}`,
+        where :math:`\tau_{FWHM}` is the Full-Width-Half-Maximum duration
         of the intensity distribution of the pulse.
 
     t_peak : float (in second)
         The time at which the laser envelope reaches its maximum amplitude,
         i.e. :math:`t_{peak}` in the above formula.
 
     cep_phase : float (in radian), optional
-        The Carrier Envelope Phase (CEP), i.e. :math:`\\phi_{cep}`
+        The Carrier Envelope Phase (CEP), i.e. :math:`\phi_{cep}`
         in the above formula (i.e. the phase of the laser
         oscillation, at the time where the laser envelope is maximum)
 
@@ -66,6 +66,7 @@ class GaussianProfile(CombinedLongitudinalTransverseProfile):
     >>> import matplotlib.pyplot as plt
     >>> from lasy.laser import Laser
     >>> from lasy.profiles.gaussian_profile import GaussianProfile
+    >>> from lasy.utils.laser_utils import get_full_field
     >>> # Create profile.
     >>> profile = GaussianProfile(
     ...     wavelength=0.6e-6,  # m
@@ -84,10 +85,10 @@ class GaussianProfile(CombinedLongitudinalTransverseProfile):
     ...     profile=profile
     ... )
     >>> # Visualize field.
-    >>> E_rt, extent = laser.get_full_field()
-    >>> extent[:2] *= 1e6
-    >>> extent[2:] *= 1e15
-    >>> rmin, rmax, tmin, tmax = extent
+    >>> E_rt, extent = get_full_field(laser)
+    >>> extent[2:] *= 1e6
+    >>> extent[:2] *= 1e15
+    >>> tmin, tmax, rmin, rmax = extent
     >>> vmax = np.abs(E_rt).max()
     >>> plt.imshow(
     ...     E_rt,

lasy/profiles/longitudinal/gaussian_profile.py

@@ -13,23 +13,23 @@ class GaussianLongitudinalProfile(LongitudinalProfile):
 
     .. math::
 
-        \\mathcal{L}(t) = \\exp\\left( - \\frac{(t-t_{peak})^2}{\\tau^2}
-                        + i\\omega_0t_{peak} \\right)
+        \mathcal{L}(t) = \exp\left( - \frac{(t-t_{peak})^2}{\tau^2}
+                        + i\omega_0t_{peak} \right)
 
     Parameters
     ----------
     tau : float (in second)
-        The duration of the laser pulse, i.e. :math:`\\tau` in the above
-        formula. Note that :math:`\\tau = \\tau_{FWHM}/\\sqrt{2\\log(2)}`,
-        where :math:`\\tau_{FWHM}` is the Full-Width-Half-Maximum duration
+        The duration of the laser pulse, i.e. :math:`\tau` in the above
+        formula. Note that :math:`\tau = \tau_{FWHM}/\sqrt{2\log(2)}`,
+        where :math:`\tau_{FWHM}` is the Full-Width-Half-Maximum duration
         of the intensity distribution of the pulse.
 
     t_peak : float (in second)
         The time at which the laser envelope reaches its maximum amplitude,
         i.e. :math:`t_{peak}` in the above formula.
 
     cep_phase : float (in radian), optional
-        The Carrier Enveloppe Phase (CEP), i.e. :math:`\\phi_{cep}`
+        The Carrier Enveloppe Phase (CEP), i.e. :math:`\phi_{cep}`
         in the above formula (i.e. the phase of the laser
         oscillation, at the time where the laser envelope is maximum)
     """

lasy/profiles/transverse/gaussian_profile.py

@@ -7,35 +7,38 @@ class GaussianTransverseProfile(TransverseProfile):
     r"""
     Derived class for the analytic profile of a Gaussian laser pulse.
 
-    More precisely, at focus (`z_foc=0`), the transverse envelope
+    More precisely, at focus (``z_foc=0``), the transverse envelope
     (to be used in the :class:CombinedLongitudinalTransverseLaser class)
     corresponds to:
 
     .. math::
 
-        \\mathcal{T}(x, y) = \\exp\\left( -\\frac{x^2 + y^2}{w_0^2} \\right)
+        \mathcal{T}(x, y) = \exp\left( -\frac{x^2 + y^2}{w_0^2} \right)
 
     Parameters
     ----------
     w0 : float (in meter)
         The waist of the laser pulse, i.e. :math:`w_0` in the above formula.
 
+    wavelength : float (in meter), optional
+        The main laser wavelength :math:`\lambda_0` of the laser.
+        (Only needed if ``z_foc`` is different than 0.)
+
     z_foc : float (in meter), optional
-        Position of the focal plane. (The laser pulse is initialized at `z=0`.)
+        Position of the focal plane. (The laser pulse is initialized at
+        ``z=0``.)
 
-    wavelength : float (in meter), optional
-        The main laser wavelength :math:`\\lambda_0` of the laser.
-        (Only needed if `z_foc` is different than 0.)
-
-    .. warning::
-
-        In order to initialize the pulse out of focus, you can either:
-            - Use a non-zero `z_foc`
-            - Use `z_foc=0` (i.e. initialize the pulse at focus) and then
-              call `laser.propagate(-z_foc)`
-        Both methods are in principle equivalent, but note that the first
-        method uses the paraxial approximation, while the second method does
-        not make this approximation.
+    Warnings
+    --------
+    In order to initialize the pulse out of focus, you can either:
+
+    - Use a non-zero ``z_foc``
+    - Use ``z_foc=0`` (i.e. initialize the pulse at focus) and then call
+      ``laser.propagate(-z_foc)``
+
+    Both methods are in principle equivalent, but note that the first
+    method uses the paraxial approximation, while the second method does
+    not make this approximation.
     """
 
     def __init__(self, w0, wavelength=None, z_foc=0):

lasy/profiles/transverse/hermite_gaussian_profile.py

@@ -14,12 +14,12 @@ class HermiteGaussianTransverseProfile(TransverseProfile):
 
     .. math::
 
-        \\mathcal{T}(x, y) = \\,
-        \\sqrt{\\frac{2}{\\pi}} \\sqrt{\\frac{1}{2^{n} n! w_0}}\\,
-        \\sqrt{\\frac{1}{2^{n} n! w_0}}\\,
-        H_{n_x}\\left ( \\frac{\\sqrt{2} x}{w_0}\\right )\\,
-        H_{n_y}\\left ( \\frac{\\sqrt{2} y}{w_0}\\right )\\,
-        \\exp\\left( -\\frac{x^2+y^2}{w_0^2} \\right)
+        \mathcal{T}(x, y) = \,
+        \sqrt{\frac{2}{\pi}} \sqrt{\frac{1}{2^{n} n! w_0}}\,
+        \sqrt{\frac{1}{2^{n} n! w_0}}\,
+        H_{n_x}\left ( \frac{\sqrt{2} x}{w_0}\right )\,
+        H_{n_y}\left ( \frac{\sqrt{2} y}{w_0}\right )\,
+        \exp\left( -\frac{x^2+y^2}{w_0^2} \right)
 
     where  :math:`H_{n}` is the Hermite polynomial of order :math:`n`.
 

lasy/profiles/transverse/jinc_profile.py

@@ -11,7 +11,7 @@ class JincTransverseProfile(TransverseProfile):
 
     .. math::
 
-        \\mathcal{T}(x, y) = 2\\frac{J_1(r/w_0)}{r/w_0} \\textrm{, with } r=\\sqrt{x^2+y^2}
+        \mathcal{T}(x, y) = 2\frac{J_1(r/w_0)}{r/w_0} \textrm{, with } r=\sqrt{x^2+y^2}
 
     where :math:`J_1` is the Bessel function of the first kind of order one
 

lasy/profiles/transverse/laguerre_gaussian_profile.py

@@ -14,12 +14,12 @@ class LaguerreGaussianTransverseProfile(TransverseProfile):
 
     .. math::
 
-        \\mathcal{T}(x, y) = r^{|m|}e^{-im\\theta} \\,
-        L_p^{|m|}\\left( \\frac{2 r^2 }{w_0^2}\\right )\\,
-        \\exp\\left( -\\frac{r^2}{w_0^2} \\right)
+        \mathcal{T}(x, y) = r^{|m|}e^{-im\theta} \,
+        L_p^{|m|}\left( \frac{2 r^2 }{w_0^2}\right )\,
+        \exp\left( -\frac{r^2}{w_0^2} \right)
 
-    where :math:`x = r \\cos{\\theta}`,
-    :math:`y = r \\sin{\\theta}`, :math:`L_p^{|m|}` is the
+    where :math:`x = r \cos{\theta}`,
+    :math:`y = r \sin{\theta}`, :math:`L_p^{|m|}` is the
     Generalised Laguerre polynomial of radial order :math:`p` and
     azimuthal order :math:`|m|`
 

lasy/profiles/transverse/super_gaussian_profile.py

@@ -11,7 +11,7 @@ class SuperGaussianTransverseProfile(TransverseProfile):
 
     .. math::
 
-        \\mathcal{T}(x, y) = \\exp\\left( -\\left({\\frac{{x^2 + y^2}}{w_0^2}}\\right)^{\\dfrac{n}{2}} \\right)
+        \mathcal{T}(x, y) = \exp\left( -\left({\frac{{x^2 + y^2}}{w_0^2}}\right)^{\dfrac{n}{2}} \right)
 
     Parameters
     ----------