Minor Doc Fixes

.github/workflows/release-notes.yml

@@ -22,7 +22,7 @@ jobs:
         git fetch origin main
         if git diff origin/main --exit-code include/ceed/*; then
           echo "No public interface changes detected"
-        elif git diff origin/main --exit-code doc/sphinx/source/releasenotes.rst; then
+        elif git diff origin/main --exit-code CHANGELOG.md; then
           echo "API changes detected, but release notes not updated"
           exit 1
         fi

Doxyfile

@@ -1127,7 +1127,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ./README.md
+USE_MDFILE_AS_MAINPAGE =
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common

doc/sphinx/source/CHANGELOG.md

@@ -0,0 +1 @@
+../../../CHANGELOG.md

doc/sphinx/source/conf.py

@@ -100,13 +100,9 @@
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = [
+    "doc/README.md",
     "examples/README.md",
-    "examples/ceed/README.md",
-    "examples/fluids/README.md",
-    "examples/nek/README.md",
-    "examples/petsc/README.md",
-    "examples/solid/README.md",
-    "examples/deal.II/README.md",
+    "examples/*/README.md",
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

doc/sphinx/source/index.md

@@ -15,7 +15,7 @@ precision
 libCEEDdev
 Contributing <CONTRIBUTING>
 Code of Conduct <CODE_OF_CONDUCT>
-releasenotes
+Release Notes <CHANGELOG>
 ```
 
 # Indices and tables

examples/README.md

@@ -13,7 +13,7 @@ For more details, please see the dedicated [documentation section](https://libce
 
 The Center for Efficient Exascale Discretizations (CEED) uses Bakeoff Problems (BPs) to test and compare the performance of high-order finite element implementations.
 The definitions of the problems are given on the ceed [website](https://ceed.exascaleproject.org/bps/).
-Each of the following bakeoff problems that use external discretization libraries (such as deal.II, MFEM, PETSc, and Nek5000) are located in the subdirectories `deal.II/`, `mfem/`, `petsc/`, and `nek5000/`, respectively.
+Each of the following bakeoff problems that use external discretization libraries (such as deal.II, MFEM, PETSc, and Nek5000) are located in the directories `examples/deal.II/`, `examples/mfem/`, `examples/nek5000/`, and `examples/petsc/`, respectively.
 
 Here we provide a short summary:
 
@@ -32,16 +32,16 @@ Here we provide a short summary:
 * - `mfem`
   - * BP1 (scalar mass operator) with $Q=P+1$
     * BP3 (scalar Laplace operator) with $Q=P+1$
+* - `nek5000`
+  - * BP1 (scalar mass operator) with $Q=P+1$
+    * BP3 (scalar Laplace operator) with $Q=P+1$
 * - `petsc`
   - * BP1 (scalar mass operator) with $Q=P+1$
     * BP2 (vector mass operator) with $Q=P+1$
     * BP3 (scalar Laplace operator) with $Q=P+1$
     * BP4 (vector Laplace operator) with $Q=P+1$
     * BP5 (collocated scalar Laplace operator) with $Q=P$
     * BP6 (collocated vector Laplace operator) with $Q=P$
-* - `nek5000`
-  - * BP1 (scalar mass operator) with $Q=P+1$
-    * BP3 (scalar Laplace operator) with $Q=P+1$
 :::
 
 These are all **T-vector**-to-**T-vector** and include parallel scatter, element scatter, element evaluation kernel, element gather, and parallel gather (with the parallel gathers/scatters done externally to libCEED).

examples/bps.md

@@ -49,9 +49,9 @@ each defined for index sets $i,j \; \in \; \{1,\dots,n\}$.
 
 (laplace-operator)=
 
-## Laplace's Operator
+## Laplace Operator
 
-The Laplace's operator used in BP3-BP6 is defined via the following variational formulation, i.e., find $u \in V^p$ such that for all $v \in V^p$
+The Laplace operator used in BP3-BP6 is defined via the following variational formulation, i.e., find $u \in V^p$ such that for all $v \in V^p$
 
 $$
 a(v,u) = \langle v,f \rangle , \,

examples/ceed/README.md

@@ -1,16 +1,16 @@
-## libCEED Basic Examples
+# libCEED Basic Examples
 
 Two examples are provided that rely only upon libCEED without any external libraries.
 
-### Example 1: ex1-volume
+## Example 1: ex1-volume
 
 This example uses the mass matrix to compute the length, area, or volume of a region, depending upon runtime parameters.
 
-### Example 2: ex2-surface
+## Example 2: ex2-surface
 
 This example uses the diffusion matrix to compute the surface area of a region, in 1D, 2D or 3D, depending upon runtime parameters.
 
-### Example 3: ex3-volume
+## Example 3: ex3-volume
 
 This example uses the mass matrix to compute the length, area, or volume of a region, depending upon runtime parameters.
 Unlike ex1, this example also adds the diffusion matrix to add a zero contribution to this calculation while demonstrating the ability of libCEED to handle multiple basis evaluation modes on the same input and output vectors.

examples/deal.II/README.md

@@ -1,4 +1,4 @@
-## libCEED deal.II Example
+# libCEED deal.II Example
 
 An example how to write libCEED operators (BP1-BP6) within the open-source finite element library [deal.II](https://www.dealii.org/).
 As reference, operators are presented that use the native matrix-free infrastructure.

examples/fluids/README.md

@@ -1,4 +1,4 @@
-## libCEED: Navier-Stokes Example
+# libCEED: Navier-Stokes Example
 
 This page provides a description of the Navier-Stokes example for the libCEED library, based on PETSc.
 

examples/index.md

@@ -4,7 +4,7 @@
 
 This section contains a mathematical description of all examples provided with libCEED
 in the {file}`examples/` directory.
-These examples are meant to demonstrate use of libCEED from standalone definition of operators to integration with external libraries such as [PETSc](https://www.mcs.anl.gov/petsc), [MFEM](https://mfem.org), and [Nek5000](https://nek5000.mcs.anl.gov/), as well as more substantial mini-apps.
+These examples are meant to demonstrate use of libCEED from standalone definition of operators to integration with external libraries such as [PETSc](https://www.mcs.anl.gov/petsc), [deal.II](https://dealii.org), [MFEM](https://mfem.org), and [Nek5000](https://nek5000.mcs.anl.gov/), as well as more substantial mini-apps.
 
 ```{toctree}
 :maxdepth: 2

examples/mfem/README.md

@@ -1,4 +1,4 @@
-## libCEED MFEM Examples
+# libCEED MFEM Examples
 
 These examples show to write libCEED operators (BP1 and BP3) within the open-source finite element library [MFEM](https://www.mfem.org/).
 

examples/nek/README.md

@@ -1,6 +1,6 @@
-## libCEED + Nek5000 Examples
+# libCEED + Nek5000 Examples
 
-### Prerequisites
+## Prerequisites
 
 Nek5000 v19.0 or greater must be [installed](https://nek5000.mcs.anl.gov/getstarted/) to run these examples.
 It is assumed to exist at `../../../Nek5000` (a sibling to the libCEED directory) or at a path defined in the environment variable `NEK5K_DIR`.
@@ -17,7 +17,7 @@ They can be built using
 ```
 See also the [Nek5000 documentation](https://nek5000.mcs.anl.gov/getstarted/).
 
-### Building the Nek5000 examples
+## Building the Nek5000 examples
 
 You can build the Nek5000 libCEED examples with the command `make bps`.
 
@@ -33,7 +33,7 @@ Note: Nek5000 examples must be built sequentially.
 Due to the Nek5000 build process, multiple examples cannot be built in parallel.
 At present, there is only one Nek5000 example file to build, which handles both CEED BP 1 and CEED BP 3.
 
-### Running Nek5000 examples
+## Running Nek5000 examples
 
 You can run the Nek5000 libCEED examples by invoking `nek-examples.sh` script.
 The syntax is:

examples/nek/bps/bps.h

@@ -45,6 +45,7 @@ CEED_QFUNCTION(massf)(void *ctx, CeedInt Q, const CeedScalar *const *in, CeedSca
 
   return 0;
 }
+
 // *****************************************************************************
 //   BP 3
 // *****************************************************************************

examples/petsc/README.md

@@ -1,8 +1,8 @@
-## libCEED + PETSc Examples
+# libCEED + PETSc Examples
 
 This page provides a description of the CEED bakeoff problem examples for the libCEED library, based on PETSc.
 
-### CEED bakeoff problems with raw mesh management - bpsraw
+## CEED bakeoff problems with raw mesh management - bpsraw
 
 This code solves the CEED bakeoff problems on a structured grid generated and referenced using only low-level communication primitives.
 
@@ -14,7 +14,7 @@ In addition to the common arguments, the following arguments may be set:
 
 - `-local`             - Target number of locally owned DoFs per process
 
-### CEED bakeoff problems with DMPlex - bps
+## CEED bakeoff problems with DMPlex - bps
 
 This code solves the CEED bakeoff problems on a unstructured grid using DMPlex.
 
@@ -27,7 +27,7 @@ In addition to the common arguments, the following arguments may be set:
 - `-mesh`              - Read mesh from file
 - `-cells`             - Number of cells per dimension
 
-#### Running a suite
+### Running a suite
 
 Some run-time arguments can be passed lists, which allows a single `mpiexec` invocation to run many experiments.
 For example
@@ -39,7 +39,7 @@ For example
 which will sample from the `4*4*3=48` specified combinations, each of which will run a problem-size sweep of 600, 1200, 2400, 4800, 9600, 192000 FEM nodes per MPI rank.
 The resulting log file can be read by the Python plotting scripts in `benchmarks/`.
 
-### CEED bakeoff problems with DMPlex and PCMG - multigrid
+## CEED bakeoff problems with DMPlex and PCMG - multigrid
 
 This code solves the CEED bakeoff problems on a unstructured grid using DMPlex with p-multigrid implemented in PCMG.
 
@@ -52,7 +52,7 @@ In addition to the common arguments, the following arguments may be set:
 - `-mesh`              - Read mesh from file
 - `-cells`             - Number of cells per dimension
 
-### Command line arguments
+## Command line arguments
 
 The following arguments can be specified for all of the above examples:
 
@@ -63,7 +63,7 @@ The following arguments can be specified for all of the above examples:
 - `-test`              - Testing mode (do not print unless error is large)
 - `-benchmark`         - Benchmarking mode (prints benchmark statistics)
 
-### libCEED example to compute surface area using DMPlex - area
+## libCEED example to compute surface area using DMPlex - area
 
 This example uses the mass matrix to compute the surface area of a cube or a discrete cubed-sphere, defined via DMPlex.
 
@@ -75,7 +75,7 @@ or
 
 `./area -problem sphere -ceed [ceed-resource] -petscspace_degree [degree]`
 
-#### Command line arguments
+### Command line arguments
 
 The following arguments can be specified for the area example:
 

examples/python/README.md

@@ -1,12 +1,12 @@
-## libCEED Python Examples
+# libCEED Python Examples
 
 These examples are written using libCEED's Python interface.
 
-### Tutorials
+## Tutorials
 
 These Jupyter notebooks explore the concepts of the libCEED API, including how to install the Python interface and the usage of each API object, with interactive examples.
 
-### Basic Examples
+## Basic Examples
 
 The basic libCEED C examples in the folder `/examples/ceed` are also available as Python examples.
 

interface/ceed-config.c

@@ -22,7 +22,7 @@ const char *CeedBuildConfiguration = CEED_BUILD_CONFIGURATION;
   @param[out] git_version A static string containing the Git commit description.
 
   If `git describe --always --dirty` fails, the string `"unknown"` will be provided.
-  This could occur if Git is not installed or if libCEED is not being built from a repository, for example.`
+  This could occur if Git is not installed or if libCEED is not being built from a repository, for example.
 
   @ref Developer
 

interface/ceed-preconditioning.c

@@ -438,7 +438,7 @@ static inline int CeedOperatorLinearAssembleAddDiagonalComposite(CeedOperator op
 }
 
 /**
-  @brief Build nonzero pattern for non-composite CeedOperator`.
+  @brief Build nonzero pattern for non-composite `CeedOperator`.
 
   Users should generally use @ref CeedOperatorLinearAssembleSymbolic().
 
@@ -1611,7 +1611,7 @@ int CeedOperatorGetOperatorAssemblyData(CeedOperator op, CeedOperatorAssemblyDat
 
   The `CeedOperatorAssemblyData` holds an array with references to every active `CeedBasis` used in the `CeedOperator`.
   An array with references to the corresponding active `CeedElemRestriction` is also stored.
-  For each active `CeedBasis, the `CeedOperatorAssemblyData` holds an array of all input and output @ref CeedEvalMode for this `CeedBasis`.
+  For each active `CeedBasis`, the `CeedOperatorAssemblyData` holds an array of all input and output @ref CeedEvalMode for this `CeedBasis`.
   The `CeedOperatorAssemblyData` holds an array of offsets for indexing into the assembled `CeedQFunction` arrays to the row representing each @ref CeedEvalMode.
   The number of input columns across all active bases for the assembled `CeedQFunction` is also stored.
   Lastly, the `CeedOperatorAssembly` data holds assembled matrices representing the full action of the `CeedBasis` for all @ref CeedEvalMode.

interface/ceed-qfunction.c

@@ -756,7 +756,7 @@ int CeedQFunctionCreateInteriorByName(Ceed ceed, const char *name, CeedQFunction
   @brief Create an identity `CeedQFunction`.
 
   Inputs are written into outputs in the order given.
-  This is useful for `CeedOperator that can be represented with only the action of a `CeedElemRestriction` and `CeedBasis`, such as restriction and prolongation operators for p-multigrid.
+  This is useful for `CeedOperator` that can be represented with only the action of a `CeedElemRestriction` and `CeedBasis`, such as restriction and prolongation operators for p-multigrid.
   Backends may optimize `CeedOperator` with this `CeedQFunction` to avoid the copy of input data to output fields by using the same memory location for both.
 
   @param[in]  ceed     `Ceed` object used to create the `CeedQFunction`

interface/ceed-vector.c

@@ -761,7 +761,7 @@ int CeedVectorScale(CeedVector x, CeedScalar alpha) {
 
   @param[in,out] y     target `CeedVector` for sum
   @param[in]     alpha scaling factor
-  @param[in]     x     second `CeedVector`, must be different than ``y`
+  @param[in]     x     second `CeedVector`, must be different than `y`
 
   @return An error code: 0 - success, otherwise - failure