Improve automatic manual conversion

benchmarks/advection/doc/advection.md

@@ -1,8 +1,8 @@
-#### Advection stabilization benchmarks
+# Advection stabilization benchmarks
 
 The underlying PDEs of the temperature and compositional field are typically
 advection-dominated and as such, require a stabilization scheme, see
-[\[sec:advection-stabilization\]][1] for an introduction for the methods
+{ref}`sec:advection-stabilization` for an introduction for the methods
 implemented in .
 
 We have several benchmarks to test the robustness, quality of solutions (size

benchmarks/annulus/doc/annulus.md

@@ -1,4 +1,4 @@
-#### The 2D annulus benchmark
+# The 2D annulus benchmark
 
 *This section was contributed by C. Thieulot and E. G. Puckett.*
 

benchmarks/buiter_et_al_2016_jsg/doc/buiter_et_al_2016_jsg.md

@@ -1,4 +1,4 @@
-#### Brittle thrust wedges benchmark
+# Brittle thrust wedges benchmark
 
 *This section was contributed by Sibiao Liu, Stephanie Sparks, John Naliboff,
 Cedric Thieulot, and Wolfgang Bangerth.*

benchmarks/burstedde/doc/burstedde.md

@@ -1,4 +1,4 @@
-#### The Burstedde variable viscosity benchmark
+# The Burstedde variable viscosity benchmark
 
 *This section was contributed by Iris van Zelst.*
 
@@ -92,7 +92,7 @@ the `benchmarks/burstedde/burstedde.cc` file that accompanies this benchmark.
 
 We will use the input file `benchmarks/burstedde/burstedde.prm` as input,
 which is very similar to the input file `benchmarks/inclusion/adaptive.prm`
-discussed above in Section [\[sec:benchmark-inclusion\]][5]. The major
+discussed above in Section {ref}`sec:benchmark-inclusion`. The major
 changes for the 3D polynomial Stokes benchmark are listed below:
 
 ``` prmfile

benchmarks/crameri_et_al/doc/crameri_et_al.md

@@ -1,11 +1,11 @@
-#### The Crameri et al. benchmarks
+# The Crameri et al. benchmarks
 
 *This section was contributed by Ian Rose.*
 
 This section follows the two free surface benchmarks described by Crameri et
 al. (Crameri et al. 2012).
 
-##### Case 1: Relaxation of topography.
+## Case 1: Relaxation of topography.
 
 The first benchmark involves a high viscosity lid sitting on top of a lower
 viscosity mantle. There is an initial sinusoidal topography which is then
@@ -22,7 +22,7 @@ are in Figure [1][].
 </div>
 
 The complete parameter file for this benchmark can be found in
-[benchmarks/crameri_et_al/case_1/crameri_benchmark_1.prm][], the most relevant
+[benchmarks/crameri_et_al/case_1/crameri_benchmark_1.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/crameri_et_al/case_1/crameri_benchmark_1.prm), the most relevant
 parts of which are excerpted here:
 
 ``` prmfile
@@ -38,7 +38,7 @@ in the `ReboundBox` subsection.
 The characteristic timescales of topography relaxation are significantly
 smaller than those of mantle convection. Taking timesteps larger than this
 relaxation timescale tends to cause sloshing instabilities, which are
-described further in Section&nbsp;[\[sec:freesurface\]][2]. Some sort of
+described further in Section&nbsp;{ref}`sec:freesurface`. Some sort of
 stabilization is required to take large timesteps. In this benchmark, however,
 we are interested in the relaxation timescale, so we are free to take very
 small timesteps (in this case, 0.01 times the CFL number). As can be seen in
@@ -53,7 +53,7 @@ comparison are basically indistinguishable.
 
 </div>
 
-##### Case 2: Dynamic topography.
+## Case 2: Dynamic topography.
 
 Case two is more complicated. Unlike the case one, it occurs over mantle
 convection timescales. In this benchmark there is the same high viscosity lid
@@ -83,7 +83,7 @@ $\sim 800$ meters.
 
 Again, we excerpt the most relevant parts of the parameter file for this
 benchmark, with the full thing available in
-[benchmarks/crameri_et_al/case_2/crameri_benchmark_2.prm][]. Here we use the
+[benchmarks/crameri_et_al/case_2/crameri_benchmark_2.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/crameri_et_al/case_2/crameri_benchmark_2.prm). Here we use the
 &ldquo;Multicomponent&rdquo; material model, which allows us to easily set up
 a number of compositional fields with different material properties. The first
 compositional field corresponds to background mantle, the second corresponds

benchmarks/davies_et_al/doc/davies_et_al.md

@@ -38,7 +38,7 @@ $${Nu}_{T} = \frac{-Q_{T}\ln(f)}{2\pi{r_{\max}}(1-f)k}$$ and similarly
 $${Nu}_{B} = \frac{-Q_{B}f\ln(f)}{2\pi{r_{\min}}(1-f)k}.$$ $Q_T$ and $Q_B$ are
 heat fluxes that can readily compute through the `heat flux statistics`
 postprocessor (see
-Section [\[parameters:Postprocess/List of postprocessors\]][2]). For
+Section {ref}`parameters:Postprocess/List of postprocessors`). For
 further details on the nondimensionalization and equations used for each
 approximation, refer to Davies et al.
 
@@ -66,15 +66,15 @@ is important here though is that the system evolve to four convective cells
 since we are only interested in the long term, steady state behavior.
 
 The model is relatively straightforward to set up, basing the input file on
-that discussed in Section [\[sec:shell-simple-2d\]][3]. The full input
-file can be found at [benchmarks/davies_et_al/case-1.1.prm][], with the
+that discussed in Section {ref}`sec:shell-simple-2d`. The full input
+file can be found at [benchmarks/davies_et_al/case-1.1.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/davies_et_al/case-1.1.prm), with the
 interesting parts excerpted as follows:
 
 ``` prmfile
 ```
 
 We use the same trick here as in
-Section [\[sec:cookbooks-simple-box\]][4] to produce a model in which the
+Section {ref}`sec:cookbooks-simple-box` to produce a model in which the
 density $\rho(T)$ in the temperature equation [\[eq:temperature\]][5] is
 almost constant (namely, by choosing a very small thermal expansion
 coefficient) as required by the benchmark, and instead prescribe the desired
@@ -101,9 +101,9 @@ of the entire system satisfies the Stokes equations with their boundary
 conditions. In other words, the solution of the problem is not unique: given a
 solution, adding a solid body rotation yields another solution. We select
 arbitrarily the one that has no net rotation (see
-Section [\[parameters:Nullspace_20removal\]][6]). The section in the
+Section {ref}`parameters:Nullspace_20removal`). The section in the
 input file that is relevant is then as follows (the full input file resides at
-[benchmarks/davies_et_al/case-2.1.prm][]):
+[benchmarks/davies_et_al/case-2.1.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/davies_et_al/case-2.1.prm)):
 
 ``` prmfile
 ```
@@ -126,9 +126,9 @@ Case 2.2 is described as follows:
 
 In other words, we have an increased Rayleigh number and begin with the final
 steady state of case 2.1. To start the model where case 2.1 left off, the
-input file of case 2.1, [benchmarks/davies_et_al/case-2.1.prm][], instructs to
+input file of case 2.1, [benchmarks/davies_et_al/case-2.1.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/davies_et_al/case-2.1.prm), instructs to
 checkpoint itself every few time steps (see
-Section [\[sec:checkpoint-restart\]][7]). If case 2.2 uses the same
+Section {ref}`sec:checkpoint-restart`). If case 2.2 uses the same
 output directory, we can then resume the computations from this checkpoint
 with an input file that prescribes a different Rayleigh number and a later
 input time:
@@ -138,7 +138,7 @@ input time:
 
 We increase the Rayleigh number to $10^5$ by increasing the magnitude of
 gravity in the input file. The full script for case 2.2 is located in
-[benchmarks/davies_et_al/case-2.2.prm][]
+[benchmarks/davies_et_al/case-2.2.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/davies_et_al/case-2.2.prm)
 
 (sec:benchmarks:davies_et_al:case2.3)=
 ## Case 2.3: BA_Ra103_vv_FS.
@@ -159,11 +159,11 @@ The Rayleigh number is smaller here (and is selected using the gravity
 parameter in the input file, as before), but the more important change is that
 the viscosity is now a function of temperature. At the time of writing, there
 is no material model that would implement such a viscosity, so we create a
-plugin that does so for us (see Sections [\[sec:extending\]][8] and
-[\[sec:write-plugin\]][9] in general, and
-Section [\[sec:material-models\]][10] for material models in particular).
+plugin that does so for us (see Sections {ref}`sec:extending` and
+{ref}`sec:write-plugin` in general, and
+Section {ref}`sec:material-models` for material models in particular).
 The code for it is located in
-[benchmarks/davies_et_al/case-2.3-plugin/VoT.cc][] (where “VoT” is
+[benchmarks/davies_et_al/case-2.3-plugin/VoT.cc](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/davies_et_al/case-2.3-plugin/VoT.cc) (where “VoT” is
 short for “viscosity as a function of temperature”) and is
 essentially a copy of the `simpler` material model. The primary change
 compared to the `simpler` material model is the line about the viscosity in
@@ -188,12 +188,12 @@ evaluate(const typename Interface<dim>::MaterialModelInputs &in,
 }
 ```
 
-Using the method described in Sections&nbsp;[\[sec:benchmark-run\]][11] and
-[\[sec:write-plugin\]][9], and the files in the
+Using the method described in Sections&nbsp;{ref}`sec:benchmark-run` and
+{ref}`sec:write-plugin`, and the files in the
 `benchmarks/davies_et_al/case-2.3-plugin`, we can compile our new material
 model into a shared library that we can then reference from the input file.
 The complete input file for case 2.3 is located in
-[benchmarks/davies_et_al/case-2.3.prm][] and contains among others the
+[benchmarks/davies_et_al/case-2.3.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/davies_et_al/case-2.3.prm) and contains among others the
 following parts:
 
 ``` prmfile

benchmarks/doneahuerta/doc/doneahuerta.md

@@ -1,4 +1,4 @@
-#### Donea & Huerta 2D box geometry benchmark
+# Donea & Huerta 2D box geometry benchmark
 
 *This section was contributed by Cedric Thieulot.*
 

benchmarks/gravity_mantle/doc/gravity_mantle.md

@@ -1,10 +1,10 @@
-#### Gravity field generated by mantle density variations
+# Gravity field generated by mantle density variations
 
 *This section was contributed by C. Thieulot and L. Jeanniot.*
 
 The gravity postprocessor has been benchmarked in
-Section [\[sec:benchmark-thin-shell-gravity\]][1] and
-[\[sec:benchmark-thick-shell-gravity\]][2]. We use it here in an Earth-like
+Section {ref}`sec:benchmark-thin-shell-gravity` and
+{ref}`sec:benchmark-thick-shell-gravity`. We use it here in an Earth-like
 context: the tomography model S40RTS (Ritsema et al. 2011) is used and scaled
 so as to provide temperature anomalies, which themselves incorporated in the
 Simple material model yield a density distribution for the entire Earth mantle
@@ -13,7 +13,7 @@ $R\textsubscript{inner} \leq r \leq R\textsubscript{outer}$ with
 $R\textsubscript{inner}=3480~\si{\km}$ and
 $R\textsubscript{outer}=6251~\si{\km}$. The use of the S20RTS/S40RTS
 tomography model and its parameterization is detailed in
-Section [\[sec:cookbooks-S20RTS\]][3].
+Section {ref}`sec:cookbooks-S20RTS`.
 
 We set the global refinement to 3 so that the mesh counts
 $12\times 16^3=49,152$ cells. This means that the radial resolution is
@@ -41,7 +41,7 @@ The gravity postprocessor computes the gravitational potential, acceleration
 vector and gradient at a given radius (here chosen to be
 $6371+250=6621~\si{\km}$) on a regular $2\si{\degree}$-latitude-longitude grid
 (see also the cookbook of
-Section [\[sec:benchmark-thin-shell-gravity\]][1]) and returns the
+Section {ref}`sec:benchmark-thin-shell-gravity`) and returns the
 results in the `gravity-00000` file to be found in the `output-gravity` folder
 inside the regular output folder.
 

benchmarks/gravity_thick_shell/doc/gravity_thick_shell.md

@@ -1,4 +1,4 @@
-#### Thick shell gravity benchmark
+# Thick shell gravity benchmark
 
 *This section was contributed by Cedric Thieulot.*
 

benchmarks/gravity_thin_shell/doc/gravity_thin_shell.md

@@ -1,4 +1,4 @@
-#### Thin shell gravity benchmark
+# Thin shell gravity benchmark
 
 *This section was contributed by Cedric Thieulot, Bart Root and Paul Bremner.*
 

benchmarks/hollow_sphere/doc/hollow_sphere.md

@@ -1,4 +1,4 @@
-#### The hollow sphere benchmark
+# The hollow sphere benchmark
 
 This benchmark is based on Thieulot (Thieulot 2017) in which an analytical
 solution to the isoviscous incompressible Stokes equations is derived in a

benchmarks/inclusion/doc/inclusion.md

@@ -1,5 +1,5 @@
 (sec:benchmarks:inclusion)=
-#### The “inclusion” Stokes benchmark
+# The “inclusion” Stokes benchmark
 
 The “inclusion” benchmark again solves a problem with a
 discontinuous viscosity, but this time the viscosity is chosen in such a way

benchmarks/layeredflow/doc/layeredflow.md

@@ -1,4 +1,4 @@
-#### Layered flow with viscosity contrast
+# Layered flow with viscosity contrast
 
 *This section was contributed by Cedric Thieulot.*
 

benchmarks/onset-of-convection/doc/onset-of-convection.md

@@ -1,4 +1,4 @@
-#### Onset of convection benchmark
+# Onset of convection benchmark
 
 *This section was contributed by Max Rudolph, based on a course assignment for
 “Geodynamic Modeling” at Portland State University.*

benchmarks/operator_splitting/doc/operator_splitting.md

@@ -1,4 +1,4 @@
-#### Benchmarks for operator splitting
+# Benchmarks for operator splitting
 
 *This section was contributed by Juliane Dannberg.*
 
@@ -81,7 +81,7 @@ advection. The reactions for exponential decay $$\begin{aligned}
   \mathfrak{c}_0 e^{\lambda t} \text{ with } \lambda = - \log(2)/t_{1/2},\end{aligned}$$
 where $\mathfrak{c}_0$ is the initial composition and $t_{1/2}$ is the half
 life, are implemented in a shared library
-([benchmarks/operator_splitting/exponential_decay/exponential_decay.cc][]). As
+([benchmarks/operator_splitting/exponential_decay/exponential_decay.cc](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/operator_splitting/exponential_decay/exponential_decay.cc)). As
 we split the time-stepping of advection and reactions, there are now two
 different time steps in the model: We control the advection time step using
 the ‘Maximum time step’ parameter (as the velocity is essentially
@@ -103,7 +103,7 @@ also set $t_{1/2}=10$, which is implemented as a parameter in the
 ```
 
 The complete parameter file for this setup can be found in
-[benchmarks/operator_splitting/exponential_decay/exponential_decay.base.prm][].
+[benchmarks/operator_splitting/exponential_decay/exponential_decay.base.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/operator_splitting/exponential_decay/exponential_decay.base.prm).
 
 Figure [1][] shows the convergence behavior of these models: As there is
 no advection, the advection time step does not influence the error (blue data
@@ -132,7 +132,7 @@ now $$\begin{aligned}
   \sin (2\pi(x-t v_0)) \, \mathfrak{c}_0 e^{\lambda z t}.\end{aligned}$$ $v_0$
 is the constant velocity, which we set to 0.01 m/s. The parameter file for
 this setup can be found in
-[benchmarks/operator_splitting/advection_reaction/advection_reaction.base.prm][].
+[benchmarks/operator_splitting/advection_reaction/advection_reaction.base.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/operator_splitting/advection_reaction/advection_reaction.base.prm).
 
 <div class="center">
 

benchmarks/polydiapirs/doc/polydiapirs.md

@@ -1,4 +1,4 @@
-#### Polydiapirism
+# Polydiapirism
 
 *This section was contributed by Cedric Thieulot.*
 

benchmarks/rayleigh_taylor_instability/doc/rayleigh_taylor_instability.md

@@ -1,4 +1,4 @@
-#### The Rayleigh-Taylor instability
+# The Rayleigh-Taylor instability
 
 *This section was contributed by Cedric Thieulot.*
 

benchmarks/sinking_block/doc/sinking_block.md

@@ -1,4 +1,4 @@
-#### The sinking block benchmark
+# The sinking block benchmark
 
 This benchmark is based on the benchmark presented in (Gerya 2010) and
 extended in (Thieulot 2011). It consists of a two-dimensional

benchmarks/slab_detachment/doc/slab_detachment.md

@@ -1,4 +1,4 @@
-#### The slab detachment benchmark
+# The slab detachment benchmark
 
 *This section was contributed by Cedric Thieulot and Anne Glerum.*
 

benchmarks/solitary_wave/doc/solitary_wave.md

@@ -9,7 +9,7 @@ melt through a compacting and dilating matrix is the propagation of solitary
 waves (e.g. (Simpson and Spiegelman 2011; Keller, May, and Kaus 2013;
 Schmeling 2000)). The benchmark is intended to test the accuracy of the
 solution of the two-phase flow equations as described in Section
-[\[sec:melt_transport\]][1] and makes use of the fact that there is an
+{ref}`sec:melt_transport` and makes use of the fact that there is an
 analytical solution for the shape of solitary waves that travel through a
 partially molten rock with a constant background porosity without changing
 their shape and with a constant wave speed. Here, we follow the setup of the
@@ -50,8 +50,8 @@ Figure [1][] illustrates the model setup.
 </div>
 
 The parameter file and material model for this setup can be found in
-[benchmarks/solitary_wave/solitary_wave.prm][] and
-[benchmarks/solitary_wave/solitary_wave.cc][]. The most relevant sections are
+[benchmarks/solitary_wave/solitary_wave.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/solitary_wave/solitary_wave.prm) and
+[benchmarks/solitary_wave/solitary_wave.cc](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/solitary_wave/solitary_wave.cc). The most relevant sections are
 shown in the following paragraph.
 
 ``` prmfile

benchmarks/tosi_et_al_2015_gcubed/doc/tosi_et_al_2015_gcubed.md

@@ -1,4 +1,4 @@
-#### The Tosi et al. benchmarks
+# The Tosi et al. benchmarks
 
 *This section was contributed by Anne Glerum.*
 
@@ -14,18 +14,18 @@ dimensions with free slip boundary conditions. The initial temperature
 distribution considers a linear depth profile with a slight perturbation to
 start convection. Top and bottom boundaries are set to a fixed temperature
 value. The parameters shared between the benchmark cases can be found in
-[benchmarks/tosi_et_al_2015_gcubed/Tosi_base.prm][]. The other input files
+[benchmarks/tosi_et_al_2015_gcubed/Tosi_base.prm](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/tosi_et_al_2015_gcubed/Tosi_base.prm). The other input files
 describe the variations on this base model, which pertain to the rheological
 description. The specific rheologies used are implemented in
-[benchmarks/tosi_et_al_2015_gcubed/tosi.cc][] and describe a linear and a
+[benchmarks/tosi_et_al_2015_gcubed/tosi.cc](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/tosi_et_al_2015_gcubed/tosi.cc) and describe a linear and a
 plastic component of the viscosity: $$\begin{aligned}
   \eta_\text{linear}(T,z) &= \exp(-\ln(\eta_T) T + \ln(\eta_Z) z)
   \label{eq:tosi-benchmark-lin-visc} \\
   \eta_\text{plastic}(\dot\epsilon) &= \eta^\ast + \frac{\sigma_y}{\sqrt{\dot\epsilon:\dot\epsilon}}
   \label{eq:tosi-benchmark-plast-visc}\end{aligned}$$ where $\eta^\ast$ is the
 constant effective viscosity at high stresses and $\sigma_y$ the yield stress.
 
-##### Case 1: Temperature-dependent convection.
+## Case 1: Temperature-dependent convection.
 
 The first benchmark considers a viscosity that only depends on temperature
 (Eq. [\[eq:tosi-benchmark-lin-visc\]][1], with $\gamma_Z=0$). When run to
@@ -36,13 +36,13 @@ average temperature, the Nusselt number at the top and bottom of the domain,
 the RMS velocity at the top boundary and in the whole domain, and the maximum
 velocity at the surface. These quantities can be queried by using several of
 the postprocessors, but the additional postprocessor in
-[benchmarks/tosi_et_al_2015_gcubed/tosi.cc][] is needed to compute the average
+[benchmarks/tosi_et_al_2015_gcubed/tosi.cc](https://www.github.com/geodynamics/aspect/blob/main/benchmarks/tosi_et_al_2015_gcubed/tosi.cc) is needed to compute the average
 rate of work done against gravity, the average rate of viscous dissipation,
 and the error between them. Differences between these diagnostic quantities of
 the 11 codes that participated in the benchmark effort are smaller than 5% for
 their preferred mesh resolution.
 
-##### Case 2: Viscoplastic convection.
+## Case 2: Viscoplastic convection.
 
 Case 2 includes a strain rate-dependent component in the viscosity, which is
 harmonically averaged with the linear component (see also the code snippet

benchmarks/viscosity_grooves/doc/viscosity_grooves.md

@@ -1,4 +1,4 @@
-#### Viscosity grooves benchmark
+# Viscosity grooves benchmark
 
 *This benchmark was designed by Dave May and this section was contributed by
 Cedric Thieulot.*