sphinx online documentation

[tjhei]

Meta issue for anything related to the new documentation.

• [x] initial conversion #4593
• [x] parse version number from ~/VERSION
• [ ] move output into ASPECT build directory
• [x] setup readthedocs
• [x] update links on website, README, etc.
• [ ] make a helpful index page
• [x] run doc in CI?

[gassmoeller]

We have a very early version of the documentation online here: https://aspect-doc.readthedocs.io/en/latest/user/index.html

[cmills1095]

• [X] Introduction
  • [X] Referencing ASPECT
  • [X] Acknowledgements
• [x] Geodynamic modeling assumptions and numerical methods in ASPECT
  • [X] Basic equations
  • [X] A comment on adiabatic heating
  • [X] Boundary conditions
  • [X] Two-dimensional models
  • [X] Comments on the final set of equations
  • [X] Coefficients
  • [X] Coefficient self-consistency
  • [X] Coefficient averaging
  • [X] Dimensional or non-dimensionalized equations?
  • [X] Years or seconds??
  • [X] Static or dynamic pressure?
  • [X] Pressure normalization
  • [X] Initial conditions and the adiabatic pressure/temperature
  • [X] Compositional fields
  • [X] Constitutive laws
  • [X] Numerical methods
  • [X] Approximate equations
  • [X] ALA
  • [X] TALA
  • [X] BA
  • [X] ICA
  • [X] Choosing a formulation in ASPECT
  • [X] Mass conservation approximation
  • [X] Temperature equation approximation
  • [X] Approximation of the buoyancy term
  • [X] Reference state: The adiabatic profile
  • [X] Combined formulations
  • [x] Advection Stabilization
  • [x] SUPG Stabilization
  • [x] Entropy viscosity
  • [x] Free surface calculation
  • [x] Arbitrary Lagrangian-Eulerian implementation
  • [x] Free surface stabilization
  • [x] Calculations with melt transport
  • [x] Nullspace removal
  • [x] Particles
  • [x] Geometric Multigrid
• [x] Installation
  • [x] Docker Container
  • [x] Installing Docker and downloading the ASPECT image
  • [x] Running ASPECT models
  • [x] Developing ASPECT within a container
  • [x] Virtual Machine
  • [x] Installing VM software and setting up the virtual machine
  • [x] Running ASPECT models
  • [x] Local installation
  • [x] System prerequisites
  • [x] Using candi to compile dependencies
  • [x] Obtaining ASPECT and initial configuration
  • [x] Compiling ASPECT and generating documentation
• [x] Running ASPECT
  • [x] First steps
  • [x] Overview
  • [x] Selecting between 2d and 3d runs
  • [x] Debug or optimized mode
  • [x] Visualizing results
  • [x] Visualization the graphical output using Visit
  • [x] Visualizing statistical data
  • [x] Large data issues for parallel computations
  • [x] Checkpoint/restart support
  • [x] Making ASPECT run faster
  • [x] Debug vs optimized mode
  • [x] Adjusting solver tolerances
  • [x] Adjusting solver preconditioner tolerances
  • [x] Using lower order elements for the temperature/compositional discretization
  • [x] Limiting postprocessing
  • [x] Switching off pressure normalization
  • [x] Regularizing models with large coefficient variation
  • [x] Using multithreading
  • [x] Input parameter files
  • [x] The structure of parameter files
  • [x] Categories of parameters
  • [x] A note on the syntax of formulas in input files
  • [x] Compatibility of input files with newer ASPECT versions
  • [x] A graphical user interface for editing ASPECT parameter files
  • [x] Installing parameter-GUI
  • [x] Using ASPECT-GUI
• [x] Cookbooks
  • [x] How to set up computations
  • [x] Simple setups
  • [x] Convection in a 2d box (Arushi working on)
  • [x] Convection in a 3d box (Yijun working on)
  • [x] Convection in a box with prescribed, variable velocity boundary conditions (Yijun working on)
  • [x] Using passive and active compositional fields
  • [x] Using particles
  • [x] Using a free surface (Chris M working on)
  • [x] Using a free surface in a model with a crust
  • [x] Averaging material properties
  • [x] Prescribed internal velocity constraints (Daniel working on)
  • [x] Prescribing internal velocity constraints with ASCII files
  • [x] Artificial viscosity smoohting
  • [x] Tracking finite strain
  • [x] Reading in compositional initial composition files generated with geomIO
  • [x] Using lazy expression syntax for if-else-statements in function expressions
  • [x] Convection in a 2d box with a phase transition
  • [x] Visualizing phase diagrams
  • [x] Plume in a 2D chunk
  • [x] Geophysical setups
  • [x] Simple convection in a quarter of a 2d annulus (Chris M working on)
  • [x] Simple convection in a spherical 3d shell (PR Pending)
  • [x] Postprocessing spherical 3D convection (PR Pending)
  • [x] 3D convection with an Earth-like initial condition (PR Pending)
  • [x] Using reconstructed surface velocities by GPlates (PR Pending)
  • [x] 2D compressible convection with a reference profile and material properties from BurnMan
  • [x] Convection using a pressure-temperature look-up table and the rheology of Steinberger and Calderwood (2006)
  • [x] Reproducing rheology of Morency and Doin, 2004
  • [x] Crustal deformation
  • [x] Continental extension (John N will work on this cookbook)
  • [x] Inner core convection (Juliane will look at this)
  • [x] Melt migration in a 2D mantle convection model
  • [x] Melt migration in a 2D mid-ocean ridge model
  • [x] Kinematically-driven 2d oceanic subduction
  • [x] Teaching setups
  • [x] Running a geodynamic model (PR pending)
  • [x] Convective and conductive heat flow: Cooling of oceanic lithosphere (PR pending)
  • [x] Onset of convection (PR pending)
  • [x] Magnetic lineations on the sea floor (PR pending)
• [x] Benchmarks
  • [x] Running benchmarks that require code
  • [x] Onset of convection benchmark
  • [x] The van Keken thermomechanical composition benchmark
  • [x] Computation of the van Keken Problem with the Volume-of-Fluid Interface Tracking Method
  • [x] The Bunge et al. mantle convection experiments
  • [x] The Rayleigh-Taylor instability
  • [x] Polydiapirism
  • [x] The sinking block benchmark
  • [x] The SolCx Stokes benchmark
  • [x] The SolKz Stokes benchmark
  • [x] The "inclusion" Stokes benchmark
  • [x] The Burstedded variable viscosity benchark
  • [x] The slab detachment benchmark
  • [x] The hollow sphere benchmark
  • [x] The 2D annulus benchmark
  • [x] The "Stokes' law" benchmark
  • [x] Latent heat benchmark
  • [x] The 2D cylindrical shell benchmarks by Davies et al.
  • [x] The Carmeri et al. benchmarks
  • [x] The solitary wave benchmark
  • [x] Benchmarks for operator splitting (PR pending)
  • [x] The Tosi et al. benchmarks (PR pending)
  • [x] Layered flow with viscosity contrast (PR pending)
  • [x] Donea & Huerta 2D box geometry benchmark (PR pending)
  • [x] Advection stabilization benchmarks (PR pending)
  • [x] Yamauchi & Takei anelastic shear wave velocity-temperature conversion benchmark (PR pending)
  • [x] Thin shell gravity benchmark (PR pending)
  • [x] Thick shell gravity benchmark (PR pending)
  • [x] Gravity field generated by mantle density variations (PR pending)
  • [x] Brittle thrust wedges benchmark (PR pending)
• [x] Extending and contributing to ASPECT
  • [x] The idea of plugins and the SimulatorAccess and Introspection classes
  • [x] How to write a plugin
  • [x] How to write a cookbook
  • [x] Parameter file
  • [x] Plugins and other additional file
  • [x] Section in the manual
  • [x] Available plugin types
  • [x] Material models
  • [x] Heating models
  • [x] Geometry models
  • [x] Initial conditions
  • [x] Prescribed velocity boundary conditions
  • [x] Temperature boundary conditions
  • [x] Postprocessors: Evaluating the solution after each time step
  • [x] Visualization postprocessors
  • [x] Mesh refinement criteria
  • [x] Criteria for terminating a simulation
  • [x] Compatibility of plugins with newer ASPECT versions
  • [x] Extending ASPECT through the signals mechanism
  • [x] Extending the basic solver
  • [x] Testing ASPECT
  • [x] Running tests
  • [x] Writing tests
  • [x] Test properties
  • [x] Contributing to ASPECT's development
  • [x] Future plans fo ASPECT
• [x] Finding answers to more questions
• [x] Run-time input parameters

[cmills1095]

https://aspect-documentation.readthedocs.io/en/latest/user/index.html

[tjhei]

awesome. Would it make sense to get rid of the index page and always show user/ ? I don't like that we don't have the navbar on the left on the front page.

[danieldouglas92]

I'll take the prescribed_velocity cookbook!

[tjhei]

How are we going to refer to ASPECT: just as "ASPECT" or using <span class="smallcaps">ASPECT</span>?

[cmills1095]

How are we going to refer to ASPECT: just as "ASPECT" or using <span class="smallcaps">ASPECT</span>?

Do the tags actually change anything? It seemed like it didn’t so I deleted most of them, but it would be simple to use them if thats what y’all want

[cmills1095]

awesome. Would it make sense to get rid of the index page and always show user/ ? I don't like that we don't have the navbar on the left on the front page.

This (and some other issues I’ve seen brought up) are a function of the pydata theme we’re using. I’m in no way married to that theme and it should be easy to change, here’s the available themes that I’m aware of: https://sphinx-themes.org/

[bobmyhill]

I don't think the index problem is due to the theme. At least, the sample at https://sphinx-themes.org/ behaves differently to the current aspect docs.

The index should normally reside at the left hand side, or in the drop down menu for smartphones.

(Personally, I like the standard readthedocs theme, but pydata is also good.)

[alarshi]

I will work on the Artificial viscosity smoothing cookbook and convection in 2D box.

[tjhei]

The one we are currently using is not great on mobile (or a narrow browser window) because the index should be in a dropdown instead of taking up the whole screen. I don't have a strong preference for a theme, but I think we might want to customize the colors a little bit (like a reddish header or sidebar or something)

[tjhei]

Do the tags actually change anything? It seemed like it didn’t so I deleted most of them, but it would be simple to use them if thats what y’all want

What to people think? Is there a way to define a macro so that we can change one central location, @cmills1095 ?

[gassmoeller]

Regarding the theme: I like what Menno did with the WorldBuilder documentation, should we copy that? https://gwb.readthedocs.io/en/latest/

[bobmyhill]

@tjhei, I think it's the structure of index.md that controls how the index is displayed, not the theme. See, for example, Menno's index.md: https://raw.githubusercontent.com/GeodynamicWorldBuilder/WorldBuilder/main/doc/sphinx/index.md

Vs. the current ASPECT one: https://raw.githubusercontent.com/geodynamics/aspect/main/doc/sphinx/index.md

[tjhei]

Vs. the current ASPECT one:

This is not sphinx/index.md by the way but in a subdirectory /user/.

[bobmyhill]

Ah yes, sorry. Comment updated. Nevertheless, the full TOC would be in the drop down if it were specified in https://raw.githubusercontent.com/geodynamics/aspect/main/doc/sphinx/index.md

[cmills1095]

It seems important to clarify what is meant by "clean up the formatting," a phrase I've been using quite liberally without explaining. Here's a list (which may be updated if I remember something else) of what I'm doing whenever I "clean up" an .md file representing a section/subsection/cookbook/benchmark:

• Headers: Are headers properly formatted, with no duplicates? See quickref.md

• Code blocks, figures, tables, prm files, web links, footnotes - Make sure they're properly formatted. see quickref.md for guidelines. Figures that are referenced in cookbook or benchmark documentation should be present in the same directory as the markdown file. Figures that are referenced in NON-cookbook/benchmark manual pages should be in doc/sphinx/_static/images (maybe?) and you may have to move them into that folder from wherever they currently are (probably doc/manual).

• Math formatting - inline math formatting is usually setup correctly already. Math blocks may need review. See quickref.md for proper formatting.

• References to equations, figures, tables, etc. - see quickref for proper formatting; note that some files reference equations in other files.

• Citations - these were unfortunately hard-coded into the text by the auto-conversion so it can be easy to miss them. See quickref.md for how to properly format citations. You may have to dive into references.bib to find out what the proper citation code is, but ideally I would like the citation codes to be changed to be intuitive, so that we can simply use the convention 'firstauthor:year' for single author, 'firstauthor:secondauthor:year' for two, or 'firstauthor:etal:year' for more than two. However, as of now most of references.bib is 'ZPF86' and 'KMM2010' - which I change when I get the chance. There are also a lot of duplicate entries in references.bib and I delete these when I see them (though I'm careful to make absolutely sure they're duplicates, sometimes its same authors, same year, slightly different title or something like that).

• References to other sections (NON-parameter files) - Properly format (see quickref.md). Most labels did not come over with the autoconversion; I'd like the labels to be as intuitive as possible and follow a predictable convention, which is how I've tried to set them up so far. Note that its very possible for a reference in file A to point to a file B which does not have a label, in which case you'll have to add a label to file B and include that edit as part of the pull request.

• References to parameter files - not much we can do about these right now; if the file has some parameter references, leave it as is and add a TODO box like

  :::{admonition} TODO
  [PARAMETER_REFERENCE] refers to a file which is not yet set up.
  :::

• General text formatting - delete stray html tags, fix any typos. Be aware that for some reason, some cookbooks/benchmarks files will just have all instances of the word ASPECT deleted and I don't know why. So keep an eye out for sentences that look like "The remainder of this section shows a number of applications of ."

• Notes/warnings/etc - These seem to have not carried over from the autoconversion. See quickref.md for formatting and copy/paste them from the pdf manual (I recommend having the pdf manual open whenever you're editing a section anyway) or the tex file if it has a lot of math symbols.

A file which has been checked in my above mega-checklist comment should have all of the above points fixed/working properly. I am currently working my way through the manual page by page to fix each of these things - though some can and has been addressed en masse with clever scripting :-)

Manual authors, please let me know if you have comments about anything I've said here - particularly about the image locations, and the re-naming of citation tags and section tags. I'm sort of making this up as I go and taking a lot of liberties with your years of labor

[bangerth]

On 5/19/22 18:33, cmills1095 wrote:

Manual authors, please let me know if you have comments about anything I've said here - particularly about the image locations, and the re-naming of citation tags and section tags.

These two are conceptually the right thing to do, but they break the current pdf manual. We should only do that if we decide that we're not going to build the pdf manual any more every night.

[cmills1095]

On 5/19/22 18:33, cmills1095 wrote: Manual authors, please let me know if you have comments about anything I've said here - particularly about the image locations, and the re-naming of citation tags and section tags. These two are conceptually the right thing to do, but they break the current pdf manual. We should only do that if we decide that we're not going to build the pdf manual any more every night.

The references.bib file I'm editing is in doc/sphinx and separate from the one the pdf manual references. And when I said moving images, I really meant copying them, for now. Though we could just as easily leave the images in their current folder and reference them like ../../../../manual/image.pdf . This shouldn't affect the pdf manual, right?

[bangerth]

Editing a copy is fine. For both the bib file and the pictures, creating copies is conceptually problematic, but I think we intend to get rid of the originals at some point, so that's ok with me.

[cmills1095]

Issue: Sphinx doesn't support sub-figures, and forums seem to indicate they have no intention of changing that. There is an easy way to make subfigures work by putting them in a list-tables; it looks good, but its not a figure and so won't be numbered as a figure and can't be referenced by a figure number, so probably not acceptable for our purposes. The alternative is to consolidate figures in inkscape, which is tedious but I've done one to make sure it works and its not too difficult. My question is: is there any reason we'd want to leave two subfigures as separate png files? Or can I consolidate and then delete the originals?

[bangerth]

If you ever want to re-use parts of the figure, it's super tedious to get them back out. Can a figure be only a single image file? It can't be anything else than a single file?

[cmills1095]

If you ever want to re-use parts of the figure, it's super tedious to get them back out. Can a figure be only a single image file? It can't be anything else than a single file?

That seems to be the case, unfortunately

[Wang-yijun]

I'm working on the "Convection in a 3d box" and "Convection in a box with prescribed, variable velocity boundary conditions" cookbooks.

[bangerth]

What's left here?