Merge pull request #1829 from CEED/jeremy/documentation-markers

Use HTML comments as doc inclusion markers

Author: jeremylt

README.md

@@ -27,7 +27,7 @@ The CEED research is supported by the [Exascale Computing Project](https://exasc
 
 For more details on the CEED API see the [user manual](https://libceed.org/en/latest/).
 
-<!-- % gettingstarted-inclusion-marker-->
+<!-- getting-started-inclusion -->
 
 ## Building
 
@@ -243,6 +243,8 @@ Bit-for-bit reproducibility is important in some applications.
 However, some libCEED backends use non-deterministic operations, such as `atomicAdd` for increased performance.
 The backends which are capable of generating reproducible results, with the proper compilation options, are highlighted in the list above.
 
+<!-- getting-started-exclusion -->
+
 ## Examples
 
 libCEED comes with several examples of its usage, ranging from standalone C codes in the `/examples/ceed` directory to examples based on external packages, such as MFEM, PETSc, and Nek5000.
@@ -254,7 +256,7 @@ To build the examples, set the `MFEM_DIR`, `PETSC_DIR` (and optionally `PETSC_AR
 $ cd examples/
 ```
 
-<!-- % running-examples-inclusion-marker-->
+<!-- running-examples-inclusion -->
 
 ```console
 # libCEED examples on CPU and GPU
@@ -337,7 +339,7 @@ The above code assumes a GPU-capable machine with the CUDA backends enabled.
 Depending on the available backends, other CEED resource specifiers can be provided with the `-ceed` option.
 Other command line arguments can be found in [examples/petsc](https://github.com/CEED/libCEED/blob/main/examples/petsc/README.md).
 
-<!-- % benchmarks-marker-->
+<!-- running-examples-exclusion -->
 
 ## Benchmarks
 

doc/sphinx/source/gettingstarted.md

@@ -1,5 +1,6 @@
 # Getting Started
 
 ```{include} ./README.md
-:start-after: gettingstarted-inclusion-marker-->
+:start-after: <!-- getting-started-inclusion -->
+:end-before: <!-- getting-started-exclusion -->
 ```

examples/README.md

@@ -9,7 +9,7 @@ For more details, please see the dedicated [documentation section](https://libce
 
 ## Bakeoff Problems
 
-<!-- % bps-inclusion-marker-->
+<!-- bps-inclusion -->
 
 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/).
@@ -46,7 +46,7 @@ The BPs are parametrized by the number $P$ of Gauss-Legendre-Lobatto nodal point
 A $Q$-point Gauss-Legendre quadrature is used for all BPs except BP5 and BP6, which choose $Q = P$ and Gauss-Legendre-Lobatto quadrature to collocate with the interpolation nodes.
 This latter choice is popular in applications that use spectral element methods because it produces a diagonal mass matrix (enabling easy explicit time integration) and significantly reduces the number of floating point operations to apply the operator.
 
-<!-- % bps-exclusion-marker-->
+<!-- bps-exclusion -->
 
 For a more detailed description of the operators employed in the BPs, please see the dedicated [BPs documentation section](https://libceed.org/en/latest/examples/bps.html).
 
@@ -75,6 +75,6 @@ For a detailed description, please see the corresponding [problems on the cubed-
 To build the examples, set the `MFEM_DIR`, `PETSC_DIR`, and `NEK5K_DIR` variables and, from the `examples/` directory, run
 
 ```{include} ../README.md
-:start-after: running-examples-inclusion-marker-->
-:end-before: benchmarks-marker-->
+:start-after: <!-- running-examples-inclusion -->
+:end-before: <!-- running-examples-exclusion -->
 ```

examples/bps.md

@@ -3,8 +3,8 @@
 # CEED Bakeoff Problems
 
 ```{include} ./README.md
-:start-after: bps-inclusion-marker
-:end-before: bps-exclusion-marker
+:start-after: <!-- bps-inclusion -->
+:end-before: <!-- bps-exclusion -->
 ```
 
 (mass-operator)=

examples/fluids/README.md

@@ -23,7 +23,7 @@ and run with:
 
 ## Runtime options
 
-<!-- % inclusion-fluids-marker-->
+<!-- fluids-inclusion -->
 
 The Navier-Stokes mini-app is controlled via command-line options.
 The following options are common among all problem types:

examples/fluids/index.md

@@ -9,7 +9,7 @@ Moreover, the Navier-Stokes example has been developed using PETSc, so that the
 ## Running the mini-app
 
 ```{include} README.md
-:start-after: inclusion-fluids-marker-->
+:start-after: <!-- fluids-inclusion -->
 ```
 ## The Navier-Stokes equations
 

examples/solids/README.md

@@ -22,7 +22,7 @@ and run with:
 
 ## Runtime options
 
-<!-- % inclusion-solids-marker-->
+<!-- solids-inclusion -->
 
 The elasticity mini-app is controlled via command-line options, the following of which are mandatory.
 

examples/solids/index.md

@@ -34,7 +34,7 @@ $$ (hyperelastic-cd)
 ## Running the mini-app
 
 ```{include} README.md
-:start-after: inclusion-solids-marker-->
+:start-after: <!-- solids-inclusion -->
 ```
 
 (problem-linear-elasticity)=