From a95da664621ca1feac2789b8bb582bb487354f97 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Wed, 19 Jan 2022 19:07:12 -0800 Subject: [PATCH] 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 | 8 ++++++ CONTRIBUTING.rst | 4 +-- docs/source/developers/documentation.rst | 2 +- docs/source/install/cmake.rst | 4 +-- docs/source/usage/parameters.rst | 33 ++++++++++++------------ 5 files changed, 30 insertions(+), 21 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5b2da04ba..ffc98a1ff 100644 --- a/.pre-commit-config.yaml +++ b/.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: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index dcd275919..6e0d182dd 100644 --- a/CONTRIBUTING.rst +++ b/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 ` 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. diff --git a/docs/source/developers/documentation.rst b/docs/source/developers/documentation.rst index d71501e3e..af0f6df0e 100644 --- a/docs/source/developers/documentation.rst +++ b/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 diff --git a/docs/source/install/cmake.rst b/docs/source/install/cmake.rst index 160b1a285..eeb07784c 100644 --- a/docs/source/install/cmake.rst +++ b/docs/source/install/cmake.rst @@ -156,6 +156,6 @@ Additionally, a `symbolic link `_ n Python Bindings --------------- -.. todo: +.. note:: - Coming soon :-) + TODO: Coming soon :-) diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst index a62be5336..d63deabfb 100644 --- a/docs/source/usage/parameters.rst +++ b/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. -* ``.type`` (`string`) +* ``.type`` (``string``) Indicates the element type for this lattice element. This should be one of: * ``drift`` for free drift. This requires this additional parameter: - * ``.ds`` (`float`, in meters) the segment length + * ``.ds`` (``float``, in meters) the segment length * ``quad`` for a quadrupole. This requires these additional parameters: - * ``.ds`` (`float`, in meters) the segment length + * ``.ds`` (``float``, in meters) the segment length - * ``.k`` (`float`, in inverse meters) the quadrupole strength + * ``.k`` (``float``, in inverse meters) the quadrupole strength * ``sbend`` for a bending magnet. This requires these additional parameters: - * ``.ds`` (`float`, in meters) the segment length + * ``.ds`` (``float``, in meters) the segment length - * ``.rc`` (`float`, in meters) the bend radius + * ``.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