Skip to main content
Version: Latest

Maintaining this manual

This manual is a Docusaurus site in the GeoFLAC/des3d repository, published at https://geoflac.github.io/des3d/ when changes are merged to main.

Structure​

SectionFolderContents
Getting starteddocs/getting-started/overview, installation, quickstart, running, visualizing, troubleshooting
Theorydocs/theory/formulation and numerical methods
User guidedocs/user-guide/one feature per page: model setup, numerical controls, running and output
Tutorialsdocs/tutorial/reproducible worked examples that build a model for a geoscience problem, each opening with an At a glance box
Benchmarksdocs/benchmarks/DES compared with analytical, theoretical or independent solutions, grouped by field and listed in the overview
Referencedocs/reference/configuration file and the generated parameter list
Developer guidedocs/developer/this section

Moved pages keep their published URL through a slug: in their front matter, and a renamed category page gets a redirect in docusaurus.config.ts. Link to other pages by relative file path, such as ../user-guide/running/restart.md, so the build can check the link.

Building and checking​

Docusaurus needs Node 20 or later.

yarn install
yarn build # fails on any broken link, anchor or image
yarn start # local preview at http://localhost:3000/des3d/

The parameter reference​

docs/reference/parameters.md is generated, never edited by hand. After any change to DynEarthSol's options, build both executables at that revision and run:

python3 scripts/generate_parameter_reference.py \
--exe2d /path/to/dynearthsol2d --exe3d /path/to/dynearthsol3d --source <revision>

--check with the same arguments reports whether the page is out of date.

Versions​

docs/ is the "Latest" manual, following the current source. Each tagged release has a frozen copy under versioned_docs/. A correction that also applies to a release is made in its copy too; a page for a feature that a release did not have is not added to it. When DynEarthSol tags a release, yarn docusaurus docs:version vX.Y.Z freezes the current manual.

Keeping up with DynEarthSol​

When a pull request is merged into DynEarthSol, a workflow opens an issue in this repository asking for a documentation review. User-visible changes (new or changed parameters, build options, output formats, breaking changes) are documented on the page for that feature; internal fixes are not. Tutorials record the DynEarthSol revision they were checked with in their At a glance box.