FieldType: Ensure Doxygen Works (#5330)

* `FieldType`: Top Doxygen Comment

Add a general top level comment.

* Doxygen: Expand `AMREX_ENUM`

* `FieldType`: Doxygen Oneline

Use a comment form that will still work after it gets
pasted and squashed into a single line after macro expansion.

* Doc: Include in Sphinx

* RTD: Doxygen 1.9.1 to latest

Author: ax3l

.readthedocs.yml

@@ -9,14 +9,17 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "mambaforge-latest"
+    # python: "3.11"
 
 sphinx:
-   configuration: Docs/source/conf.py
+  configuration: Docs/source/conf.py
 
-python:
-   install:
-   - requirements: Docs/requirements.txt
+conda:
+  environment: Docs/conda.yml
+# python:
+#   install:
+#   - requirements: Docs/requirements.txt
 
 formats:
   - htmlzip

Docs/Doxyfile

@@ -2245,15 +2245,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2305,14 +2305,16 @@ PREDEFINED             = AMREX_Linux=1 \
                          WARPX_QED=1 \
                          WARPX_QED_TABLE_GEN=1
 
+PREDEFINED           += "AMREX_ENUM(CLASS,...)=\"enum class CLASS : int { __VA_ARGS__ };\""
+
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
 # macro definition that is found in the sources will be used. Use the PREDEFINED
 # tag if you want to use a different macro definition that overrules the
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = AMREX_ENUM
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have

Docs/README.md

@@ -9,12 +9,13 @@ More information can be found in Docs/source/developers/documentation.rst.
 
 Install the Python requirements for compiling the documentation:
 ```
-python3 -m pip install -r Docs/requirements.txt
+cd Docs/
+python3 -m pip install -r requirements.txt
 ```
 
 ### Compiling the documentation
 
-`cd` into the `Docs/` directory and type
+Still in the `Docs/` directory, type
 ```
 make html
 ```

Docs/conda.yml

@@ -0,0 +1,12 @@
+name: readthedocs
+
+channels:
+  - conda-forge
+  - nodefaults
+
+dependencies:
+  - python
+  - doxygen
+  - pip
+  - pip:
+    - -r requirements.txt

Docs/requirements.txt

@@ -5,7 +5,7 @@
 # License: BSD-3-Clause-LBNL
 
 # WarpX PICMI bindings w/o C++ component (used for autoclass docs)
--e Python
+-e ../Python
 breathe
 docutils>=0.17.1
 

Docs/source/developers/documentation.rst

@@ -56,16 +56,15 @@ First, make sure you are in the root directory of WarpX's source and install the
 
 .. code-block:: sh
 
-    python3 -m pip install -r Docs/requirements.txt
+    cd Docs/
+    python3 -m pip install -r requirements.txt
 
 You will also need Doxygen (macOS: ``brew install doxygen``; Ubuntu: ``sudo apt install doxygen``).
 
-Then, to compile the documentation, use
+Still in the ``Docs/`` directory, compile the documentation via
 
 .. code-block:: sh
 
-    cd Docs/
-
     make html
     # This will first compile the Doxygen documentation (execute doxygen)
     # and then build html pages from rst files using sphinx and breathe.

Docs/source/developers/fields.rst

@@ -37,6 +37,13 @@ The ``MultiFab`` constructor (for, e.g., ``Ex`` on level ``lev``) is called in `
 
 By default, the ``MultiFab`` are set to ``0`` at initialization. They can be assigned a different value in ``WarpX::InitLevelData``.
 
+Field Names
+-----------
+
+The commonly used WarpX field names are defined in:
+
+.. doxygenenum:: warpx::fields::FieldType
+
 Field solver
 ------------
 

Source/Fields.H

@@ -18,25 +18,30 @@
 
 namespace warpx::fields
 {
+    /** Unique identifiers for WarpX scalar and vector fields.
+     *
+     * These are implemented as amrex::MultiFab (one or one per component "direction",
+     * respectively) and stored in the ablastr::fields::MultiFabRegister .
+     */
     AMREX_ENUM(FieldType,
         None,
-        Efield_aux, //!< Field that the particles gather from. Obtained from Efield_fp (and Efield_cp when using MR); see UpdateAuxilaryData
-        Bfield_aux, //!< Field that the particles gather from. Obtained from Bfield_fp (and Bfield_cp when using MR); see UpdateAuxilaryData
-        Efield_fp,  //!< The field that is updated by the field solver at each timestep
-        Bfield_fp,  //!< The field that is updated by the field solver at each timestep
-        Efield_fp_external, //!< Stores grid particle fields provided by the user as  through an openPMD file
-        Bfield_fp_external, //!< Stores grid particle fields provided by the user as  through an openPMD file
-        current_fp, //!< The current that is used as a source for the field solver
-        current_fp_nodal, //!< Only used when using nodal current deposition
-        current_fp_vay,   //!< Only used when using Vay current deposition
-        current_buf, //!< Particles that are close to the edge of the MR patch (i.e. in the deposition buffer) deposit to this field.
-        current_store, //!< Only used when doing subcycling with mesh refinement, for book-keeping of currents
-        rho_buf, //!< Particles that are close to the edge of the MR patch (i.e. in the deposition buffer) deposit to this field.
-        rho_fp,  //!< The charge density that is used as a source for the field solver (mostly for labframe electrostatic and PSATD)
-        F_fp, //!< Used for divE cleaning
-        G_fp, //!< Used for divB cleaning
-        phi_fp, //!< Obtained by the Poisson solver, for labframe electrostatic
-        vector_potential_fp, //!< Obtained by the magnetostatic solver
+        Efield_aux, /**< Field that the particles gather from. Obtained from Efield_fp (and Efield_cp when using MR); see UpdateAuxilaryData */
+        Bfield_aux, /**< Field that the particles gather from. Obtained from Bfield_fp (and Bfield_cp when using MR); see UpdateAuxilaryData */
+        Efield_fp,  /**< The field that is updated by the field solver at each timestep */
+        Bfield_fp,  /**< The field that is updated by the field solver at each timestep */
+        Efield_fp_external, /**< Stores grid particle fields provided by the user as  through an openPMD file */
+        Bfield_fp_external, /**< Stores grid particle fields provided by the user as  through an openPMD file */
+        current_fp, /**< The current that is used as a source for the field solver */
+        current_fp_nodal, /**< Only used when using nodal current deposition */
+        current_fp_vay,   /**< Only used when using Vay current deposition */
+        current_buf, /**< Particles that are close to the edge of the MR patch (i.e. in the deposition buffer) deposit to this field. */
+        current_store, /**< Only used when doing subcycling with mesh refinement, for book-keeping of currents */
+        rho_buf, /**< Particles that are close to the edge of the MR patch (i.e. in the deposition buffer) deposit to this field. */
+        rho_fp,  /**< The charge density that is used as a source for the field solver (mostly for labframe electrostatic and PSATD) */
+        F_fp, /**< Used for divE cleaning */
+        G_fp, /**< Used for divB cleaning */
+        phi_fp, /**< Obtained by the Poisson solver, for labframe electrostatic */
+        vector_potential_fp, /**< Obtained by the magnetostatic solver */
         vector_potential_fp_nodal,
         vector_potential_grad_buf_e_stag,
         vector_potential_grad_buf_b_stag,
@@ -45,19 +50,19 @@ namespace warpx::fields
         hybrid_current_fp_temp,
         hybrid_current_fp_ampere,
         hybrid_current_fp_external,
-        Efield_cp,  //!< Only used with MR. The field that is updated by the field solver at each timestep, on the coarse patch of each level
-        Bfield_cp,  //!< Only used with MR. The field that is updated by the field solver at each timestep, on the coarse patch of each level
-        current_cp, //!< Only used with MR. The current that is used as a source for the field solver, on the coarse patch of each level
-        rho_cp, //!< Only used with MR. The charge density that is used as a source for the field solver, on the coarse patch of each level
-        F_cp,   //!< Only used with MR. Used for divE cleaning, on the coarse patch of each level
-        G_cp,   //!< Only used with MR. Used for divB cleaning, on the coarse patch of each level
-        Efield_cax, //!< Only used with MR. Particles that are close to the edge of the MR patch (i.e. in the gather buffer) gather from this field
-        Bfield_cax, //!< Only used with MR. Particles that are close to the edge of the MR patch (i.e. in the gather buffer) gather from this field
-        E_external_particle_field, //!< Stores external particle fields provided by the user as  through an openPMD file
-        B_external_particle_field, //!< Stores external particle fields provided by the user as  through an openPMD file
-        distance_to_eb, //!< Only used with embedded boundaries (EB). Stores the distance to the nearest EB
-        edge_lengths,   //!< Only used with embedded boundaries (EB). Indicates the length of the cell edge that is covered by the EB, in SI units
-        face_areas,     //!< Only used with embedded boundaries (EB). Indicates the area of the cell face that is covered by the EB, in SI units
+        Efield_cp,  /**< Only used with MR. The field that is updated by the field solver at each timestep, on the coarse patch of each level */
+        Bfield_cp,  /**< Only used with MR. The field that is updated by the field solver at each timestep, on the coarse patch of each level */
+        current_cp, /**< Only used with MR. The current that is used as a source for the field solver, on the coarse patch of each level */
+        rho_cp, /**< Only used with MR. The charge density that is used as a source for the field solver, on the coarse patch of each level */
+        F_cp,   /**< Only used with MR. Used for divE cleaning, on the coarse patch of each level */
+        G_cp,   /**< Only used with MR. Used for divB cleaning, on the coarse patch of each level */
+        Efield_cax, /**< Only used with MR. Particles that are close to the edge of the MR patch (i.e. in the gather buffer) gather from this field */
+        Bfield_cax, /**< Only used with MR. Particles that are close to the edge of the MR patch (i.e. in the gather buffer) gather from this field */
+        E_external_particle_field, /**< Stores external particle fields provided by the user as  through an openPMD file */
+        B_external_particle_field, /**< Stores external particle fields provided by the user as  through an openPMD file */
+        distance_to_eb, /**< Only used with embedded boundaries (EB). Stores the distance to the nearest EB */
+        edge_lengths,   /**< Only used with embedded boundaries (EB). Indicates the length of the cell edge that is covered by the EB, in SI units */
+        face_areas,     /**< Only used with embedded boundaries (EB). Indicates the area of the cell face that is covered by the EB, in SI units */
         area_mod,
         pml_E_fp,
         pml_B_fp,
@@ -74,7 +79,7 @@ namespace warpx::fields
         Bfield_avg_fp,
         Efield_avg_cp,
         Bfield_avg_cp,
-        B_old, //!< Stores the value of B at the beginning of the timestep, for the implicit solver
+        B_old, /**< Stores the value of B at the beginning of the timestep, for the implicit solver */
         ECTRhofield,
         Venl
     );