Sphinx: Clean Warnings/Formatting (#50)

* Add new pre-commit configs

* Sphinx: Fix a `.. directive::`

* Contrib: Fix Linter

* rst: Fix Backticks for Verbatim Text

.pre-commit-config.yaml

@@ -30,6 +30,14 @@ repos:
 #  - id: fix-encoding-pragma
 #    exclude: ^noxfile.py$
 
+# documentation files: .rst
+-   repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.9.0
+    hooks:
+    - id: rst-backticks
+    - id: rst-directive-colons
+    - id: rst-inline-touching-normal
+
 #- repo: https://github.com/asottile/pyupgrade
 #  rev: v2.29.0
 #  hooks:

CONTRIBUTING.rst

@@ -113,7 +113,7 @@ Periodically commit your changes with
 The commit message (between quotation marks) is super important in order to follow the developments during code-review and identify bugs.
 A typical format is:
 
-.. code-block::
+.. code-block:: text
 
    This is a short, 40-character title
 
@@ -234,6 +234,6 @@ Style and conventions
 
 - ``#include`` directives in C++ have a distinct order to avoid bugs, see :ref:`the ImpactX repo structure <developers-repo-structure>` for details
 
-- For all new code, we should avoid relying on ``using namespace amrex;`` and all amrex types should be prefixed with `amrex::`.
+- For all new code, we should avoid relying on ``using namespace amrex;`` and all amrex types should be prefixed with ``amrex::``.
   Inside limited scopes, AMReX type literals can be included with ``using namespace amrex::literals;``.
   Ideally, old code should be modified accordingly.

docs/source/developers/documentation.rst

@@ -50,7 +50,7 @@ For instance, the following line will get the Doxygen documentation for ``Impact
 Building the documentation
 --------------------------
 
-To build the documentation on your local computer, you will need to install Doxygen as well as the Python module `breathe`.
+To build the documentation on your local computer, you will need to install Doxygen as well as the Python module ``breathe``.
 First, change into ``docs/`` and install the Python requirements:
 
 .. code-block:: sh

docs/source/install/cmake.rst

@@ -156,6 +156,6 @@ Additionally, a `symbolic link <https://en.wikipedia.org/wiki/Symbolic_link>`_ n
 Python Bindings
 ---------------
 
-.. todo:
+.. note::
 
-   Coming soon :-)
+   TODO: Coming soon :-)

docs/source/usage/parameters.rst

@@ -11,10 +11,10 @@ Input Parameters
 Overall simulation parameters
 -----------------------------
 
-* ``max_step`` (`integer`)
+* ``max_step`` (``integer``)
     The number of PIC cycles to perform.
 
-* ``stop_time`` (`float`; in seconds)
+* ``stop_time`` (``float``; in seconds)
     The maximum physical time of the simulation. Can be provided instead of ``max_step``. If both
     ``max_step`` and ``stop_time`` are provided, both criteria are used and the simulation stops
     when the first criterion is hit.
@@ -31,10 +31,10 @@ Overall simulation parameters
 Setting up the field mesh
 -------------------------
 
-* ``amr.n_cell`` (`2 integers in 2D`, `3 integers in 3D`)
+* ``amr.n_cell`` (2 integers in 2D, 3 integers in 3D)
     The number of grid points along each direction (on the **coarsest level**)
 
-* ``amr.max_level`` (`integer`, default: ``0``)
+* ``amr.max_level`` (``integer``, default: ``0``)
     When using mesh refinement, the number of refinement levels that will be used.
 
     Use 0 in order to disable mesh refinement.
@@ -46,17 +46,17 @@ Setting up the field mesh
 
     Note: in development; currently, ``2`` is supported.
 
-* ``amr.ref_ratio_vect`` (`3 integers for x,y,z per refined level`)
+* ``amr.ref_ratio_vect`` (3 integers for x,y,z per refined level)
     When using mesh refinement, this can be used to set the refinement ratio per direction and level, relative to the previous level.
 
     Example: for three levels, a value of ``2 2 4 8 8 16`` refines the first level by 2-fold in x and y and 4-fold in z compared to the coarsest level (level 0/mother grid); compared to the first level, the second level is refined 8-fold in x and y and 16-fold in z.
 
     Note: in development; currently allowed value: ``2 2 2``.
 
-* ``geometry.coord_sys`` (`integer`) optional (default `0`)
+* ``geometry.coord_sys`` (``integer``) optional (default ``0``)
     Coordinate system used by the simulation. 0 for Cartesian, 1 for cylindrical.
 
-* ``geometry.prob_lo`` and ``geometry.prob_hi`` (`2 floats in 2D`, `3 floats in 3D`; in meters)
+* ``geometry.prob_lo`` and ``geometry.prob_hi`` (2 floats in 2D, 3 floats in 3D; in meters)
     The extent of the full simulation box. This box is rectangular, and thus its
     extent is given here by the coordinates of the lower corner (``geometry.prob_lo``) and
     upper corner (``geometry.prob_hi``). The first axis of the coordinates is x
@@ -75,35 +75,35 @@ Domain Boundary Conditions
 Lattice Elements
 ----------------
 
-* ``lattice.elements`` (`list of strings`) optional (default: no elements)
+* ``lattice.elements`` (``list of strings``) optional (default: no elements)
     A list of names (one name per lattice element), in the order that they
     appear in the lattice.
 
-* ``<element_name>.type`` (`string`)
+* ``<element_name>.type`` (``string``)
     Indicates the element type for this lattice element. This should be one of:
 
         * ``drift`` for free drift. This requires this additional parameter:
 
-            * ``<element_name>.ds`` (`float`, in meters) the segment length
+            * ``<element_name>.ds`` (``float``, in meters) the segment length
 
         * ``quad`` for a quadrupole. This requires these additional parameters:
 
-            * ``<element_name>.ds`` (`float`, in meters) the segment length
+            * ``<element_name>.ds`` (``float``, in meters) the segment length
 
-            * ``<element_name>.k`` (`float`, in inverse meters) the quadrupole strength
+            * ``<element_name>.k`` (``float``, in inverse meters) the quadrupole strength
 
         * ``sbend`` for a bending magnet. This requires these additional parameters:
 
-            * ``<element_name>.ds`` (`float`, in meters) the segment length
+            * ``<element_name>.ds`` (``float``, in meters) the segment length
 
-            * ``<element_name>.rc`` (`float`, in meters) the bend radius
+            * ``<element_name>.rc`` (``float``, in meters) the bend radius
 
 .. _running-cpp-parameters-parallelization:
 
 Distribution across MPI ranks and parallelization
 -------------------------------------------------
 
-* ``amr.max_grid_size`` (`integer`) optional (default `128`)
+* ``amr.max_grid_size`` (``integer``) optional (default ``128`)
     Maximum allowable size of each **subdomain**
     (expressed in number of grid points, in each direction).
     Each subdomain has its own ghost cells, and can be handled by a
@@ -172,7 +172,8 @@ For example:
 Coordinates
 ^^^^^^^^^^^
 
-Besides, for profiles that depend on spatial coordinates (the plasma momentum distribution or the laser field, see below `Particle initialization` and `Laser initialization`), the parser will interpret some variables as spatial coordinates. These are specified in the input parameter, i.e., ``density_function(x,y,z)`` and ``field_function(X,Y,t)``.
+Besides, for profiles that depend on spatial coordinates (the plasma momentum distribution or the laser field, see below ``Particle initialization`` and ``Laser initialization``), the parser will interpret some variables as spatial coordinates.
+These are specified in the input parameter, i.e., ``density_function(x,y,z)`` and ``field_function(X,Y,t)``.
 
 The parser reads python-style expressions between double quotes, for instance
 ``"a0*x**2 * (1-y*1.e2) * (x>0)"`` is a valid expression where ``a0`` is a