Fix various documentation issues

include/bout/dcomplex.hxx

@@ -37,7 +37,9 @@
 
 using dcomplex = std::complex<BoutReal>;
 
-const dcomplex Im(0, 1); // 1i
+/// Imaginary unit, ``1i``
+//NOLINTNEXTLINE(readability-identifier-length)
+constexpr dcomplex Im{0, 1};
 
 /// Complex type for passing data to/from FORTRAN
 struct fcmplx {

include/bout/sys/uuid.h

@@ -261,7 +261,7 @@ class sha1 {
   size_t m_byteCount;
 };
 
-static std::mt19937 clock_gen(std::random_device{}());
+static std::mt19937 clock_gen{std::random_device{}()};
 static std::uniform_int_distribution<short> clock_dis{-32768, 32767};
 static std::atomic_short clock_sequence{clock_dis(clock_gen)};
 } // namespace detail

manual/sphinx/conf.py

@@ -31,7 +31,8 @@
 import subprocess
 import sys
 
-sys.path.append("../../tools/pylib")
+sys.path.append("../../tools/pylib/boutpp")
+sys.path.append("../../tools/pylib/boutconfig")
 
 # Are we running on readthedocs?
 on_readthedocs = os.environ.get("READTHEDOCS") == "True"
@@ -103,10 +104,7 @@ def __getattr__(cls, name):
 # readthedocs currently runs out of memory if we actually dare to try to do this
 if has_breathe:
     # Run doxygen to generate the XML sources
-    if on_readthedocs:
-        subprocess.call("cd ../doxygen; doxygen Doxyfile_readthedocs", shell=True)
-    else:
-        subprocess.call("cd ../doxygen; doxygen Doxyfile", shell=True)
+    subprocess.run(["doxygen", "Doxyfile"], cwd="../doxygen", check=True)
     # Now use breathe.apidoc to autogen rst files for each XML file
     apidoc_args = argparse.Namespace(
         destdir="_breathe_autogen/",

manual/sphinx/developer_docs/code_layout.rst

@@ -49,275 +49,85 @@ Directories
 -----------
 
 The source code for the core of BOUT++ is divided into include files
-(which can be used in physics models) in ``bout++/include``, and source
-code and low-level includes in ``bout++/src``. Many parts of the code
-are defined by their interface, and can have multiple different
-implementations. An example is the time-integration solvers: many
-different implementations are available, some of which use external
-libraries, but all have the same interface and can be used
+(which can be used in physics models) in ``bout++/include/bout``, and
+source code and low-level includes in ``bout++/src``. Many parts of
+the code are defined by their interface, and can have multiple
+different implementations. An example is the time-integration solvers:
+many different implementations are available, some of which use
+external libraries, but all have the same interface and can be used
 interchangeably. This is reflected in the directory structure inside
-``bout++/src``. A common pattern is to store individual implementations
-of an interface in a subdirectory called ``impls``.
+``bout++/src``. A common pattern is to store individual
+implementations of an interface in a subdirectory called ``impls``.
 
 ::
 
-    include/foo.hxx
+    include/bout/foo.hxx
     src/.../foo.cxx
-    src/.../foo_factory.hxx
-    src/.../foo_factory.cxx
     src/.../impls/one/one.hxx
     src/.../impls/one/one.cxx
 
 where ``foo.hxx`` defines the interface, ``foo.cxx`` implements common
-functions used in several implementations. ``foo_factory`` creates new
-implementations, and is the only file which includes all the
-implementations. Individual implementations are stored in their own
-subdirectories of ``impls``. Components which follow this pattern
-include ``fileio`` formats, ``invert/laplace`` and ``invert/parderiv``
-inversion codes, ``mesh``, and ``solver``.
+functions used in several implementations. Individual implementations
+are stored in their own subdirectories of ``impls``. Components which
+follow this pattern include ``invert/laplace`` and ``invert/parderiv``
+inversions, ``mesh``, and ``solver``.
 
-The current source code files are:
+The layout of the ``src/`` directory is as follows:
 
-- :doc:`bout++.cxx<../_breathe_autogen/file/bout_09_09_8cxx>`: Main
-  file which initialises, runs and finalises BOUT++. Currently
-  contains a `main()` function, though this is being removed shortly.
+- :doc:`src/bout++.cxx<../_breathe_autogen/file/bout_09_09_8cxx>`: Main
+  file which initialises, runs and finalises BOUT++.
 
-- field
+- ``src/field``
 
-   - :doc:`field2d.cxx<../_breathe_autogen/file/field2d_8cxx>`
-     implements the `Field2D` class. This is a scalar field which
-     varies only in :math:`x` and :math:`y` and is used for things
-     like metric tensor components and initial profiles. It supplies
-     lots of overloaded operators and functions on these objects.
+  - Implementations of "fields" (the scalars `Field2D`, `Field3D`,
+    `FieldPerp`, and vectors `Vector2D`, `Vector3D`), as well as basic
+    operations (arithmetic, :ref:`sec-algebraic-ops`, and vector
+    calculus), and :ref:`initialisation <sec-variable-init>`.
 
-   - :doc:`field3d.cxx<../_breathe_autogen/file/field3d_8cxx>`
-     implements the `Field3D` class, which varies in :math:`x`,
-     :math:`y` and :math:`z`. Since these handle a lot more memory
-     than Field2D objects, the memory management is more complicated
-     and includes reference counting. See section
-     :ref:`sec-memorymanage` for more details.
+- ``src/invert``
 
-   - :doc:`field_data.cxx<../_breathe_autogen/file/field__data_8cxx>`
-     Implements some functions in the `FieldData` class. This is a
-     mainly pure virtual interface class which is inherited by
-     `Field2D` and `Field3D`.
+  - Implementations of different inverse operators, including Fourier
+    transforms (via an interface to `FFTW <http://www.fftw.org>`_, see
+    `bout::fft::rfft` and `bout::fft::irfft`).
 
-   - :doc:`fieldperp.cxx<../_breathe_autogen/file/fieldperp_8cxx>`
-     implements a `FieldPerp` class to store slices perpendicular to
-     the magnetic field i.e. they are a function of :math:`x` and
-     :math:`z` only. This is mainly used for Laplacian inversion
-     routines, and needs to be integrated with the other fields
-     better.
+- ``src/invert/laplace``
 
-   - :doc:`initialprofiles.cxx<../_breathe_autogen/file/initialprofiles_8cxx>`
-     routines to set the initial values of fields when a simulation
-     first starts. Reads settings from the option file based on the name
-     of the variable.
+  - Implementations of some inverse generalised Laplacian operator
+    variations, where some directions may be constant. See
+    :ref:`sec-laplacian` for more details.
 
-   - :doc:`vecops.cxx<../_breathe_autogen/file/vecops_8cxx>` a
-     collection of function to operate on vectors.  Contains things
-     like ``Grad``, ``Div`` and ``Curl``, and uses a combination of
-     field differential operators (in
-     :doc:`difops.cxx<../_breathe_autogen/file/difops_8cxx>`) and
-     metric tensor components (in `Mesh`).
+- ``src/invert/parderiv``
 
-   - :doc:`vector2d.cxx<../_breathe_autogen/file/vector2d_8cxx>`
-     implements the `Vector2D` class, which uses a `Field2D` object
-     for each of its 3 components. Overloads operators to supply
-     things like dot and cross products.
+  - Inversion of parallel derivatives, intended for use in
+    preconditioners. See `InvertPar`
 
-   - :doc:`vector3d.cxx<../_breathe_autogen/file/vector3d_8cxx>`
-     implements `Vector3D` by using a `Field3D`
-     object for each component.
+- ``src/invert/pardiv``
 
-   - :doc:`where.cxx<../_breathe_autogen/file/where_8cxx>` supplies
-     functions for choosing between values based on selection
-     criteria.
+  - Inversion of parallel divergence, intended for use in
+    :ref:`sec-nonlocal-heatflux`.
 
-- invert
+- ``src/mesh``
 
-   - :doc:`fft_fftw.cxx<../_breathe_autogen/file/fft__fftw_8cxx>`
-     implements the :doc:`fft.hxx<../_breathe_autogen/file/fft_8hxx>`
-     interface by calling the Fastest Fourier Transform in the West
-     (FFTW) library.
+  - Implementations of low-level numerical routines. This includes
+    things like the :ref:`inter-process communications
+    <sec-communications>`, :ref:`boundary conditions <sec-bndryopts>`,
+    :ref:`derivative operators <sec-diffops>`, interpolation, the
+    coordinate system (including :ref:`sec-parallel-transforms`), and
+    the :ref:`sec-mesh` itself.
 
-- invert / laplace
+- ``src/physics``
 
-   - :doc:`invert_laplace.cxx<../_breathe_autogen/file/invert__laplace_8cxx>` uses Fourier
-      decomposition in :math:`z` combined with tri- and band-diagonal
-      solvers in :math:`x` to solve Laplacian problems.
+  - This contains some specialised physics operators and routines,
+    such as gyro-averaging and :ref:`sec-nonlocal-heatflux`.
 
-   - impls
+- ``src/solver``
 
-      - serial\_tri
+  - Implementations of :ref:`time integration solvers
+    <sec-time-integration>`
 
-         - :doc:`serial_tri.hxx<../_breathe_autogen/file/serial__tri_8hxx>`
+- ``src/sys``
 
-         - :doc:`serial_tri.cxx<../_breathe_autogen/file/serial__tri_8cxx>`
-
-      - serial\_band
-
-         - :doc:`serial_band.hxx<../_breathe_autogen/file/serial__band_8hxx>`
-
-         - :doc:`serial_band.cxx<../_breathe_autogen/file/serial__band_8cxx>`
-
-      - spt
-
-         - :doc:`spt.hxx<../_breathe_autogen/file/spt_8hxx>`
-
-         - :doc:`spt.cxx<../_breathe_autogen/file/spt_8cxx>`
-
-- invert / parderiv
-
-   -
-     :doc:`invert_parderiv.cxx<../_breathe_autogen/file/invert__parderiv_8cxx>`
-     inverts a problem involving only parallel :math:`y`
-     derivatives. Intended for use in some preconditioners.
-
-   - impls
-
-      - cyclic
-
-         - :doc:`cyclic.cxx<../_breathe_autogen/file/cyclic_8cxx>`
-
-         - :doc:`cyclic.hxx<../_breathe_autogen/file/cyclic_8hxx>`
-
-- :doc:`lapack_routines.cxx<../_breathe_autogen/file/lapack__routines_8cxx>` supplies an
-   interface to the LAPACK linear solvers, which are used by the
-   ``invert_laplace`` routines.
-
-- mesh
-
-   - :doc:`boundary_factory.cxx<../_breathe_autogen/file/boundary__factory_8cxx>` creates boundary
-     condition operators which can then be applied to
-     fields. Described in section :ref:`sec-BoundaryFactory`.
-
-   - :doc:`boundary_region.cxx<../_breathe_autogen/file/boundary__region_8cxx>` implements a way
-     to describe and iterate over boundary regions. Created by the
-     mesh, and then used by boundary conditions. See
-     section :ref:`sec-BoundaryRegion` for more details.
-
-   - :doc:`boundary_standard.cxx<../_breathe_autogen/file/boundary__standard_8cxx>` implements some
-     standard boundary operations and modifiers such as ``Neumann``
-     and ``Dirichlet``.
-
-   - :doc:`difops.cxx<../_breathe_autogen/file/difops_8cxx>` is a
-     collection of differential operators on scalar fields. It uses
-     the differential methods in :doc:`derivs.cxx<../_breathe_autogen/file/derivs_8cxx>` and the metric tensor
-     components in `Mesh` to compute operators.
-
-   - :doc:`interpolation.cxx<../_breathe_autogen/file/interpolation_8cxx>` contains functions
-     for interpolating fields
-
-   - :doc:`mesh.cxx<../_breathe_autogen/file/mesh_8cxx>` is the base
-     class for the `Mesh` object. Contains routines useful
-     for all `Mesh` implementations.
-
-   - impls
-
-      - bout
-
-         - :doc:`boutmesh.cxx<../_breathe_autogen/file/boutmesh_8cxx>`
-           implements a mesh interface which is compatible with BOUT
-           grid files.
-
-         - :doc:`boutmesh.hxx<../_breathe_autogen/file/boutmesh_8hxx>`
-
-- physics
-
-   - :doc:`gyro_average.cxx<../_breathe_autogen/file/gyro__average_8cxx>`
-      gyro-averaging operators
-
-   - :doc:`smoothing.cxx<../_breathe_autogen/file/smoothing_8cxx>`
-     provides smoothing routines on scalar fields
-
-   - :doc:`sourcex.cxx<../_breathe_autogen/file/sourcex_8cxx>` contains
-     some useful routines for creating sources and sinks in physics
-     equations.
-
-- solver
-
-   - :doc:`solver.cxx<../_breathe_autogen/file/solver_8cxx>` is the
-     interface for all solvers
-
-   - impls
-
-      - cvode
-
-         - :doc:`cvode.cxx<../_breathe_autogen/file/cvode_8cxx>` is the
-           implementation of `Solver` which interfaces with
-           the SUNDIALS CVODE library.
-
-         - :doc:`cvode.hxx<../_breathe_autogen/file/cvode_8hxx>`
-
-      - ida
-
-         - :doc:`ida.cxx<../_breathe_autogen/file/ida_8cxx>` is the
-           implementation which interfaces with the SUNDIALS IDA
-           library
-
-         - :doc:`ida.hxx<../_breathe_autogen/file/ida_8hxx>`
-
-      - petsc
-
-         - :doc:`petsc.cxx<../_breathe_autogen/file/petsc_8cxx>` is the
-           interface to the PETSc time integration routines
-
-         - :doc:`petsc.hxx<../_breathe_autogen/file/petsc_8hxx>`
-
-      - pvode
-
-         - :doc:`pvode.cxx<../_breathe_autogen/file/pvode_8cxx>`
-           interfaces with the 1998 (pre-SUNDIALS) version of PVODE
-           (which became CVODE).
-
-         - :doc:`pvode.hxx<../_breathe_autogen/file/pvode_8hxx>`
-
-- sys
-
-   - :doc:`boutcomm.cxx<../_breathe_autogen/file/boutcomm_8cxx>`
-
-   - :doc:`boutexception.cxx<../_breathe_autogen/file/boutexception_8cxx>`
-     is an exception class which are used for error handling
-
-   - :doc:`derivs.cxx<../_breathe_autogen/file/derivs_8cxx>` contains
-     basic derivative methods such as upwinding, central difference
-     and WENO methods. These are then used by
-     :doc:`difops.cxx<../_breathe_autogen/file/difops_8cxx>`. Details are
-     given in section :ref:`sec-diffops`.
-
-   - :doc:`msg_stack.cxx<../_breathe_autogen/file/msg__stack_8cxx>` is
-     part of the error handling system. It maintains a stack of
-     messages which can be pushed onto the stack at the start of a
-     function, then removed (popped) at the end. If an error occurs or
-     a segmentation fault is caught then this stack is printed out and
-     can help to find errors.
-
-   - :doc:`options.cxx<../_breathe_autogen/file/options_8cxx>` provides
-     an interface to the BOUT.inp option file and the command-line
-     options.
-
-   - :doc:`optionsreader.cxx<../_breathe_autogen/file/optionsreader_8cxx>`
-
-   - :doc:`output.cxx<../_breathe_autogen/file/output_8cxx>`
-
-   - :doc:`range.cxx<../_breathe_autogen/file/range_8cxx>` Provides the
-     RangeIterator class, used to iterate over a set of
-     ranges. Described in section :ref:`sec-rangeiterator`
-
-   - :doc:`timer.cxx<../_breathe_autogen/file/timer_8cxx>` a class for
-     timing parts of the code like communications and file
-     I/O. Described in section :ref:`sec-timerclass`
-
-   - :doc:`utils.cxx<../_breathe_autogen/file/utils_8cxx>` contains
-     miscellaneous small useful routines such as allocating and
-     freeing arrays.
-
-   - options
-
-      - :doc:`optionparser.hxx<../_breathe_autogen/file/optionparser_8hxx>`
-
-      - :doc:`options_ini.cxx<../_breathe_autogen/file/options__ini_8cxx>`
-
-      - :doc:`options_ini.hxx<../_breathe_autogen/file/options__ini_8hxx>`
+  - General purpose utilities used throughout the library, such as
+    `BoutException`, wrappers for C libraries like ``PETSc`` and
+    ``HYPRE``, screen and file input and output.
 

manual/sphinx/developer_docs/file_io.rst

@@ -114,5 +114,5 @@ in the first output file, which `collect` uses to get its type and dimensions.
 .. [2] Actually, the C++ I/O code should work fine even if a `FieldPerp` object is defined
        with different y-indices on different processors. This may be useful for diagnostic
        or debugging purposes. However, Python routines like `collect` and
-       :py:`boutdata.restart.redistribute` will fail because they find inconsistent
+       `boutdata.restart.redistribute` will fail because they find inconsistent
        `yindex_global` values.

manual/sphinx/developer_docs/mesh.rst

@@ -1,3 +1,5 @@
+.. _sec-mesh:
+
 Mesh
 ====
 
@@ -99,6 +101,8 @@ it::
 
 To read 2D and 3D fields, the branch-cuts need to be taken into account.
 
+.. _sec-communications:
+
 Communications
 --------------