Docs: Fix reStructuredText syntax for figures (BLAST-WarpX#5386)

While reviewing some of our documentation PRs, I noticed that we use the
`:alt:` (alternate text) syntax in a way that might be neither optimal
nor consistent with the `reStructuredText` [figure
examples](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure):

```rst
.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).
```


As a reminder, the `reStructuredText` [image
docs](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image)
describes alternate text as

> Alternate text: a short description of the image, displayed by
applications that cannot display images, or spoken by applications for
visually impaired users

_Before_ this PR, this is the output when an image is displayed:
![Screenshot from 2024-10-10
15-16-25](https://github.com/user-attachments/assets/f3b364b3-459f-4092-a350-5c64feedbbda)

_Before_ this PR, this is the output when an image is _not_ displayed
(e.g., due to a typo in the docs):
![Screenshot from 2024-10-10
15-20-20](https://github.com/user-attachments/assets/360a54e3-aded-49da-9d7f-10ae12c2e5d2)

_After_ this PR, I would propose to have this output when an image is
_not_ displayed (e.g., due to a typo in the docs):
![Screenshot from 2024-10-10
15-34-00](https://github.com/user-attachments/assets/bb59612f-f0f2-495b-9e4e-9a7678a215eb)

I think this is a better output for both users that read the docs (avoid
reading the caption twice) and visually impaired users (avoid hearing
the caption twice - the real caption is spoken too).

Note that in some cases we do not yet provide a caption. I believe we
should add a caption to all figures, but I left this out of this PR.

Author: EZoni

Docs/source/dataanalysis/picviewer.rst

@@ -2,7 +2,7 @@ PICViewer
 =========
 
 .. figure:: sample_image.png
-   :alt: picture
+   :alt: Figure not found
 
 PICViewer is a visualization GUI implemented on PyQt.
 The toolkit provides various easy-to-use functions for data analysis of

Docs/source/dataanalysis/visit.rst

@@ -26,7 +26,7 @@ Assuming that you ran a 2D simulation, here are instructions for making a simple
 Your image should look similar to the one below
 
 .. figure:: Ez.png
-   :alt: picture
+   :alt: Figure not found
 
 
 In 3D, you must apply the “Operators” -> “Slicing”

Docs/source/dataanalysis/visualpic.rst

@@ -32,9 +32,11 @@ Example: ``vpic3d -s beam -rho -Ez diags/diag1/`` could be used to visualize the
 Example: ``vpic3d -Ex diags/diag1/`` could be used to visualize the transverse focusing field :math:`E_x` in a plasma wake behind a laser pulse (linearly polarized in :math:`E_y`), see below:
 
 .. figure:: https://user-images.githubusercontent.com/1353258/233236692-4d75b12f-de44-43dc-97bd-c96b04ee68ac.png
-   :alt: Example view of a 3D rendering with VisualPIC.
+   :alt: Figure not found
    :width: 100%
 
+   Example view of a 3D rendering with VisualPIC.
+
 The **Python script** controlled rendering allows more flexible options, such as selecting and cutting views, rendering directly into an image file, looping for animations, etc.
 As with matplotlib scripts, Python script scenes can also be used to open a GUI and then browse time series interactively.
 The `VisualPIC examples <https://github.com/AngelFP/VisualPIC/tree/dev/examples>`__ provide showcases for scripting.

Docs/source/dataanalysis/workflows/tunneling.rst

@@ -52,5 +52,7 @@ To close the connection down, do this:
   * ``Ctrl+C`` the SSH tunnel in terminal B
 
 .. figure:: https://user-images.githubusercontent.com/1353258/232120440-3965fa38-9ca6-4621-a100-2da74eb899cf.png
-   :alt: Example view of remote started Jupyter service, active SSH tunnel, and local browser connecting to the service.
+   :alt: Figure not found
    :width: 100%
+
+   Example view of remote started Jupyter service, active SSH tunnel, and local browser connecting to the service.

Docs/source/theory/amr.rst

@@ -6,7 +6,7 @@ Mesh refinement
 .. _fig_ESAMR:
 
 .. figure:: ICNSP_2011_Vay_fig1.png
-   :alt: Sketches of the implementation of mesh refinement in WarpX with the electrostatic (left) and electromagnetic (right) solvers. In both cases, the charge/current from particles are deposited at the finest levels first, then interpolated recursively to coarser levels. In the electrostatic case, the potential is calculated first at the coarsest level :math:`L_0`, the solution interpolated to the boundaries of the refined patch :math:`r` at the next level :math:`L_{1}` and the potential calculated at :math:`L_1`. The procedure is repeated iteratively up to the highest level. In the electromagnetic case, the fields are computed independently on each grid and patch without interpolation at boundaries. Patches are terminated by absorbing layers (PML) to prevent the reflection of electromagnetic waves. Additional coarse patch :math:`c` and fine grid :math:`a` are needed so that the full solution is obtained by substitution on :math:`a` as :math:`F_{n+1}(a)=F_{n+1}(r)+I[F_n( s )-F_{n+1}( c )]` where :math:`F` is the field, and :math:`I` is a coarse-to-fine interpolation operator. In both cases, the field solution at a given level :math:`L_n` is unaffected by the solution at higher levels :math:`L_{n+1}` and up, allowing for mitigation of some spurious effects (see text) by providing a transition zone via extension of the patches by a few cells beyond the desired refined area (red & orange rectangles) in which the field is interpolated onto particles from the coarser parent level only.
+   :alt: Figure not found
    :width: 95%
 
    Sketches of the implementation of mesh refinement in WarpX with the electrostatic (left) and electromagnetic (right) solvers. In both cases, the charge/current from particles are deposited at the finest levels first, then interpolated recursively to coarser levels. In the electrostatic case, the potential is calculated first at the coarsest level :math:`L_0`, the solution interpolated to the boundaries of the refined patch :math:`r` at the next level :math:`L_{1}` and the potential calculated at :math:`L_1`. The procedure is repeated iteratively up to the highest level. In the electromagnetic case, the fields are computed independently on each grid and patch without interpolation at boundaries. Patches are terminated by absorbing layers (PML) to prevent the reflection of electromagnetic waves. Additional coarse patch :math:`c` and fine grid :math:`a` are needed so that the full solution is obtained by substitution on :math:`a` as :math:`F_{n+1}(a)=F_{n+1}(r)+I[F_n( s )-F_{n+1}( c )]` where :math:`F` is the field, and :math:`I` is a coarse-to-fine interpolation operator. In both cases, the field solution at a given level :math:`L_n` is unaffected by the solution at higher levels :math:`L_{n+1}` and up, allowing for mitigation of some spurious effects (see text) by providing a transition zone via extension of the patches by a few cells beyond the desired refined area (red & orange rectangles) in which the field is interpolated onto particles from the coarser parent level only.
@@ -25,7 +25,7 @@ A sketch of the implementation of mesh refinement in WarpX is given in :numref:`
 .. _fig_ESselfforce:
 
 .. figure:: ICNSP_2011_Vay_fig2.png
-   :alt: Position history of one charged particle attracted by its image induced by a nearby metallic (dirichlet) boundary. The particle is initialized at rest. Without refinement patch (reference case), the particle is accelerated by its image, is reflected specularly at the wall, then decelerates until it reaches its initial position at rest. If the particle is initialized inside a refinement patch, the particle is initially accelerated toward the wall but is spuriously reflected before it reaches the boundary of the patch whether using the method implemented in WarpX or the MC method. Providing a surrounding transition region 2 or 4 cells wide in which the potential is interpolated from the parent coarse solution reduces significantly the effect of the spurious self-force.
+   :alt: Figure not found
    :width: 95%
 
    Position history of one charged particle attracted by its image induced by a nearby metallic (dirichlet) boundary. The particle is initialized at rest. Without refinement patch (reference case), the particle is accelerated by its image, is reflected specularly at the wall, then decelerates until it reaches its initial position at rest. If the particle is initialized inside a refinement patch, the particle is initially accelerated toward the wall but is spuriously reflected before it reaches the boundary of the patch whether using the method implemented in WarpX or the MC method. Providing a surrounding transition region 2 or 4 cells wide in which the potential is interpolated from the parent coarse solution reduces significantly the effect of the spurious self-force.
@@ -35,7 +35,7 @@ The presence of the self-force is illustrated on a simple test case that was int
 .. _fig_ESselfforcemap:
 
 .. figure:: ICNSP_2011_Vay_fig3.png
-   :alt: (left) Maps of the magnitude of the spurious self-force :math:`\epsilon` in arbitrary units within one quarter of the refined patch, defined as :math:`\epsilon=\sqrt{(E_x-E_x^{ref})^2+(E_y-E_y^{ref})^2}`, where :math:`E_x` and :math:`E_y` are the electric field components within the patch experienced by one particle at a given location and :math:`E_x^{ref}` and :math:`E_y^{ref}` are the electric field from a reference solution. The map is given for the WarpX and the MC mesh refinement algorithms and for linear and quadratic interpolation at the patch refinement boundary. (right) Lineouts of the maximum (taken over neighboring cells) of the spurious self-force. Close to the interface boundary (x=0), the spurious self-force decreases at a rate close to one order of magnitude per cell (red line), then at about one order of magnitude per six cells (green line).
+   :alt: Figure not found
    :width: 95%
 
    (left) Maps of the magnitude of the spurious self-force :math:`\epsilon` in arbitrary units within one quarter of the refined patch, defined as :math:`\epsilon=\sqrt{(E_x-E_x^{ref})^2+(E_y-E_y^{ref})^2}`, where :math:`E_x` and :math:`E_y` are the electric field components within the patch experienced by one particle at a given location and :math:`E_x^{ref}` and :math:`E_y^{ref}` are the electric field from a reference solution. The map is given for the WarpX and the MC mesh refinement algorithms and for linear and quadratic interpolation at the patch refinement boundary. (right) Lineouts of the maximum (taken over neighboring cells) of the spurious self-force. Close to the interface boundary (x=0), the spurious self-force decreases at a rate close to one order of magnitude per cell (red line), then at about one order of magnitude per six cells (green line).

Docs/source/theory/boosted_frame.rst

@@ -8,7 +8,7 @@ The simulations of plasma accelerators from first principles are extremely compu
 .. _fig_Boosted_frame:
 
 .. figure:: Boosted_frame.png
-   :alt: [fig:Boosted-frame] A first principle simulation of a short driver beam (laser or charged particles) propagating through a plasma that is orders of magnitude longer necessitates a very large number of time steps. Recasting the simulation in a frame of reference that is moving close to the speed of light in the direction of the driver beam leads to simulating a driver beam that appears longer propagating through a plasma that appears shorter than in the laboratory. Thus, this relativistic transformation of space and time reduces the disparity of scales, and thereby the number of time steps to complete the simulation, by orders of magnitude.
+   :alt: Figure not found
 
    A first principle simulation of a short driver beam (laser or charged particles) propagating through a plasma that is orders of magnitude longer necessitates a very large number of time steps. Recasting the simulation in a frame of reference that is moving close to the speed of light in the direction of the driver beam leads to simulating a driver beam that appears longer propagating through a plasma that appears shorter than in the laboratory. Thus, this relativistic transformation of space and time reduces the disparity of scales, and thereby the number of time steps to complete the simulation, by orders of magnitude.
 

Docs/source/theory/boosted_frame/input_output.rst

@@ -15,7 +15,7 @@ Inputs and outputs in a boosted frame simulation
 .. _fig_inputoutput:
 
 .. figure:: Input_output.png
-   :alt: (top) Snapshot of a particle beam showing “frozen" (grey spheres) and “active" (colored spheres) macroparticles traversing the injection plane (red rectangle). (bottom) Snapshot of the beam macroparticles (colored spheres) passing through the background of electrons (dark brown streamlines) and the diagnostic stations (red rectangles). The electrons, the injection plane and the diagnostic stations are fixed in the laboratory plane, and are thus counter-propagating to the beam in a boosted frame.
+   :alt: Figure not found
    :width: 100%
 
    (top) Snapshot of a particle beam showing “frozen" (grey spheres) and “active" (colored spheres) macroparticles traversing the injection plane (red rectangle). (bottom) Snapshot of the beam macroparticles (colored spheres) passing through the background of electrons (dark brown streamlines) and the diagnostic stations (red rectangles). The electrons, the injection plane and the diagnostic stations are fixed in the laboratory plane, and are thus counter-propagating to the beam in a boosted frame.

Docs/source/theory/boundary_conditions.rst

@@ -294,7 +294,7 @@ the right boundary is reflecting.
 .. _fig_PEC_boundary_deposition:
 
 .. figure:: https://user-images.githubusercontent.com/40245517/221491318-b0a2bcbc-b04f-4b8c-8ec5-e9c92e55ee53.png
-   :alt: Plot of PEC boundary current deposition showing current vs position along the ``x``-axis.
+   :alt: Figure not found
    :width: 100%
 
    PEC boundary current deposition along the ``x``-axis. The left boundary is absorbing while the right boundary is reflecting.

Docs/source/theory/cold_fluid_model.rst

@@ -45,9 +45,9 @@ Implementation details
 .. _fig_fluid_loop:
 
 .. figure:: https://github.com/BLAST-WarpX/warpx/assets/69021085/dcbcc0e4-7899-43e4-b580-f57eb359b457
-   :alt: Figure showing fluid Loop embedded within the overall PIC loop.
+   :alt: Figure not found
 
-   Fluid Loop embedded within the overall PIC loop.
+   Fluid loop embedded within the overall PIC loop.
 
 The fluid timeloop is embedded inside the standard PIC timeloop and consists of
 the following steps: 1. Higuera and Cary push of the momentum 2. Non-inertial (momentum source)

Docs/source/theory/intro.rst

@@ -14,13 +14,13 @@ additional physics modules, etc. described in the sections linked further down.
 .. _fig-pic:
 
 .. figure:: PIC.png
-   :alt: [fig:PIC] The Particle-In-Cell (PIC) method follows the evolution of a collection of charged macro-particles (positively charged in blue on the left plot, negatively charged in red) that evolve self-consistently with their electromagnetic (or electrostatic) fields. The core PIC algorithm involves four operations at each time step: 1) evolve the velocity and position of the particles using the Newton-Lorentz equations, 2) deposit the charge and/or current densities through interpolation from the particles distributions onto the grid, 3) evolve Maxwell’s wave equations (for electromagnetic) or solve Poisson’s equation (for electrostatic) on the grid, 4) interpolate the fields from the grid onto the particles for the next particle push. Additional “add-ons” operations are inserted between these core operations to account for additional physics (e.g. absorption/emission of particles, addition of external forces to account for accelerator focusing or accelerating component) or numerical effects (e.g. smoothing/filtering of the charge/current densities and/or fields on the grid).
+   :alt: Figure not found
 
    The Particle-In-Cell (PIC) method follows the evolution of a collection of charged macro-particles (positively charged in blue on the left plot, negatively charged in red) that evolve self-consistently with their electromagnetic (or electrostatic) fields. The core PIC algorithm involves four operations at each time step: 1) evolve the velocity and position of the particles using the Newton-Lorentz equations, 2) deposit the charge and/or current densities through interpolation from the particles distributions onto the grid, 3) evolve Maxwell’s wave equations (for electromagnetic) or solve Poisson’s equation (for electrostatic) on the grid, 4) interpolate the fields from the grid onto the particles for the next particle push. Additional “add-ons” operations are inserted between these core operations to account for additional physics (e.g. absorption/emission of particles, addition of external forces to account for accelerator focusing or accelerating component) or numerical effects (e.g. smoothing/filtering of the charge/current densities and/or fields on the grid).
 
 
 .. figure:: Plasma_acceleration_sim.png
-   :alt: Plasma acceleration diagram
+   :alt: Figure not found
 
    Plasma laser-driven (top) and charged-particles-driven (bottom) acceleration (rendering from 3-D Particle-In-Cell simulations). A laser beam (red and blue disks in top picture) or a charged particle beam (red dots in bottom picture) propagating (from left to right) through an under-dense plasma (not represented) displaces electrons, creating a plasma wakefield that supports very high electric fields (pale blue and yellow). These electric fields, which can be orders of magnitude larger than with conventional techniques, can be used to accelerate a short charged particle beam (white) to high-energy over a very short distance.