Merge pull request #983 from flohorovicic/main

Japhiolite · web-flow · commit 2adca2a761da · 2025-01-31T15:37:34.000+01:00
Updates for documentation
diff --git a/.gitignore b/.gitignore
@@ -137,8 +137,17 @@ notebooks/prototype notebooks/vtk_res_model_adjusted_1
 notebooks/prototype notebooks/vtk_exp_smooth_trnasitions
 notebooks/prototype notebooks/plots
 
+# Remove the built document files - but not the static ones, which are required for the builds
 docs/build
-docs/source
+# The following files are generated locally during sphinx updates - they don't have to be part of the repo
+docs/source/examples
+docs/source/tutorials
+docs/source/Modeling\ Classes
+docs/source/GemPy\ API
+docs/source/Helper\ Classes
+docs/source/Plot
+docs/source/external
+docs/source/sg_execution_times.rst
 test/figs
 
 Profiles
diff --git a/docs/source/_images/3D_view_pyvista_example.png b/docs/source/_images/3D_view_pyvista_example.png
diff --git a/docs/source/_images/AlesModel_example.png b/docs/source/_images/AlesModel_example.png
diff --git a/docs/source/_images/data_to_model.png b/docs/source/_images/data_to_model.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -154,6 +154,7 @@
                 # 'integrations'
         ],
         "filename_pattern"       : r"\.py",
+ #       "ignore_pattern": r"(__init__\.py|ch1_7_3d_visualization\.py|mik\.py)$",  # Exclude specific files: uncomment for faster build as long as examples are broken
         "download_all_examples"  : False,  # Remove the "Download all examples" button from the top level gallery
         "within_subsection_order": FileNameSortKey,  # Sort gallery example by file name instead of number of lines (default)
         "backreferences_dir"     : 'gen_modules/backreferences',  # directory where function granular galleries are stored
diff --git a/examples/examples/geometries/a01_horizontal_stratigraphic.py b/examples/examples/geometries/a01_horizontal_stratigraphic.py
@@ -1,11 +1,15 @@
 """
-Model 1 - Horizontal stratigraphic
+Model 1 - Horizontal stratigraphy
 ==================================
 
-This script demonstrates how to create a basic model of horizontally stacked layers using GemPy,
+A simple example with horizontal layers
+
+This script demonstrates how to create a basic model with horizontally stacked layers using GemPy,
 a Python-based, open-source library for implicit geological modeling.
 """
 
+
+# %%
 # Import necessary libraries
 import gempy as gp
 import gempy_viewer as gpv
diff --git a/examples/examples/geometries/b02_fold.py b/examples/examples/geometries/b02_fold.py
@@ -2,6 +2,8 @@
 Model 2 - Anticline
 ===================
 
+Simple model of an anticline
+
 This script demonstrates how to create a geological model of an anticline structure using GemPy,
 a Python-based, open-source library for implicit geological modeling.
 """
diff --git a/examples/examples/geometries/c03_recumbent_fold.py b/examples/examples/geometries/c03_recumbent_fold.py
@@ -2,6 +2,8 @@
 Model 3 - Recumbent Fold
 ========================
 
+Modeling a recumbent fold
+
 This script demonstrates how to create a geological model of a recumbent fold using GemPy,
 a Python-based, open-source library for implicit geological modeling.
 """
diff --git a/examples/examples/geometries/d04_pinchout.py b/examples/examples/geometries/d04_pinchout.py
@@ -2,6 +2,8 @@
 Model 4 - Pinchout
 ==================
 
+Modeling of a pinchout: combining scalar fields
+
 This script demonstrates how to create a geological model with a layer of varying thickness (pinchout) using GemPy,
 a Python-based, open-source library for implicit geological modeling.
 """
diff --git a/examples/examples/geometries/e05_fault.py b/examples/examples/geometries/e05_fault.py
@@ -2,6 +2,8 @@
 Model 5 - Fault
 ===============
 
+Modeling a fault
+
 This script demonstrates how to create a simple fault model with constant offset using GemPy,
 a Python-based, open-source library for implicit geological modeling.
 """
diff --git a/examples/examples/geometries/f06_unconformity.py b/examples/examples/geometries/f06_unconformity.py
@@ -2,6 +2,8 @@
 Model 6 - Unconformity
 ======================
 
+Modeling unconformities through the combination of scalar fields
+
 This script creates an unconformity cutting an anticline structure using GemPy,
 an open-source, Python-based library for building implicit geological models.
 """
diff --git a/examples/examples/geometries/g07_combination.py b/examples/examples/geometries/g07_combination.py
@@ -2,6 +2,8 @@
 Model 7 - Combination
 ======================
 
+Combining faults and unconformities
+
 This script creates a folded domain featuring an unconformity and a fault using GemPy,
 an open-source, Python-based library for building implicit geological models.
 """
diff --git a/examples/examples/geometries/h08_more_examples.py b/examples/examples/geometries/h08_more_examples.py
@@ -2,6 +2,8 @@
 GemPy Models - Some More Complex Examples
 -----------------------------------------
 
+A set of more complex examples
+
 """
 
 # %%
diff --git a/examples/examples/real/Alesmodel.py b/examples/examples/real/Alesmodel.py
@@ -1,19 +1,16 @@
-
 """
-Alesmodel: Plotting Sections and Maps
+Model of Ales, France: Plotting Sections and Maps
 ======================================
+"""
 
 # %%
 # .. admonition:: Explanation
 #
-#       This model is generally quite unstable and requires float64 precision to find a solution.
+#       This model is generally quite unstable and requires float64 precision to determine a solution.
 #       The lack of data in one corner for the TRIAS and LIAS series causes the model to bend unrealistically,
-#       eroding the CARBO layer, which disappears in that section. The simple way to solve this is by adding more data in that area.
-#       However, I left it as is because I did not construct the model.
+#       eroding the CARBO layer, which disappears in that section. 
 #
 
-"""
-
 import gempy as gp
 import gempy_viewer as gpv
 import os
diff --git a/examples/examples/real/Claudius.py b/examples/examples/real/Claudius.py
@@ -1,7 +1,8 @@
 """
-Claudius
+Geomodeling benchmark: the "Claudius"-Model
 ========
 
+This model is part of a geomodeling benchmaring effort. More information (and, hopefully, publication) coming.
 """
 
 # %%
diff --git a/examples/examples/real/Hecho.py b/examples/examples/real/Hecho.py
@@ -1,8 +1,10 @@
 """
-Hecho
-~~~~~
+Geomodeling benchmark: the "Hecho"-Model
+========
 
+This model is part of a geomodeling benchmaring effort. More information (and, hopefully, publication) coming.
 """
+
 import os
 
 import numpy as np
diff --git a/examples/examples/real/Moureze.py b/examples/examples/real/Moureze.py
@@ -1,8 +1,10 @@
 """
-Moureze
-~~~~~~~
+Geomodeling benchmark: the "Moureze"-Model
+==========================================
 
+This model is part of a geomodeling benchmaring effort. More information (and, hopefully, publication) coming.
 """
+
 import os
 
 # %% 
diff --git a/examples/examples/real/Perth_basin.py b/examples/examples/real/Perth_basin.py
@@ -1,5 +1,5 @@
 """
-Perth basin.
+A geological model of the Perth basin, Australia
 ============
 """
 import os
diff --git a/examples/tutorials/a_getting_started/get_started.py b/examples/tutorials/a_getting_started/get_started.py
@@ -340,7 +340,7 @@
 # %%
 p2d = gpv.plot_2d(
     model=geo_model,
-    series_n=0,  # This will plot the scalar field used for the fault
+    series_n=0, 
     show_data=True,
     show_scalar=True,
     show_lith=False
@@ -515,7 +515,7 @@
 # %%
 p2d = gpv.plot_2d(
     model=geo_model,
-    series_n=1,  # This will plot the scalar field used for the fault
+    series_n=1,  # This setting will now plot the scalar field used for the fault
     show_data=True,
     show_scalar=True,
     show_lith=False
@@ -526,7 +526,7 @@
 # %%
 p2d = gpv.plot_2d(
     model=geo_model,
-    series_n=0,  # This will plot the scalar field used for the discontinuity.
+    series_n=0,  # This setting will plot the scalar field used for the discontinuity.
     show_data=True,
     show_scalar=True,
     show_lith=False
diff --git a/examples/tutorials/ch2-Geophysics/ch2_2_cell_selection.py b/examples/tutorials/ch2-Geophysics/ch2_2_cell_selection.py
@@ -2,31 +2,36 @@
 2.2: Centered Grid.
 ^^^^^^^^^^^^^^^^^^^
 
-Geophysics Preprocessing builds on the centered grid
-(https://github.com/cgre-aachen/gempy/blob/master/notebooks/tutorials/ch1-3-Grids.ipynb)
-to precompute the constant part of forward physical computations as for
-example gravity:
+"""
 
-.. math::
+# %%
+# 
+# Concept of a measurement-centered grid
+# """"""""""""""""""""""""""""""""""""""
+#
+# Geophysics Preprocessing builds on the centered grid
+# (https://github.com/cgre-aachen/gempy/blob/master/notebooks/tutorials/ch1-3-Grids.ipynb)
+# to precompute the constant part of forward physical computations as for
+# example gravity:
 
-    F_z = G_{\\rho} ||| x \\ln(y+r) + y \\ln (x+r) - z \\arctan (\\frac{x y}{z r}) |^{x_2}_{x_1}|^{y_2}_{y_1}|^{
-    z_2}_{z_1}
+# .. math::
 
+#     F_z = G_{\\rho} ||| x \\ln(y+r) + y \\ln (x+r) - z \\arctan (\\frac{x y}{z r}) |^{x_2}_{x_1}|^{y_2}_{y_1}|^{
+#     z_2}_{z_1}
 
-where we can compress the grid dependent terms as
 
-.. math::
+# where we can compress the grid dependent terms as
 
-    t_z = ||| x \ln (y+r) + y \ln (x+r)-z \\arctan ( \\frac{x y}{z r} ) |^{x_2}_{x_1}|^{y_2}_{y_1}|^{z_2}_{z_1}
+# .. math::
 
-By doing this decomposition an keeping the grid constant we can compute
-the forward gravity by simply operate:
+#     t_z = ||| x \ln (y+r) + y \ln (x+r)-z \\arctan ( \\frac{x y}{z r} ) |^{x_2}_{x_1}|^{y_2}_{y_1}|^{z_2}_{z_1}
 
-.. math::
+# By doing this decomposition an keeping the grid constant we can compute
+# the forward gravity by simply operate:
 
-    F_z = G_{\\rho} \cdot t_z
+# .. math::
 
-"""
+#     F_z = G_{\\rho} \cdot t_z
 
 
 # %%
diff --git a/examples/tutorials/z_other_tutorials/video_tutorial_model_1.py b/examples/tutorials/z_other_tutorials/video_tutorial_model_1.py
@@ -207,6 +207,18 @@
 # Video tutorial 6: 3D visualization
 # """"""""""""""""""""""""""""""""""
 
+# %%
+#.. raw:: html
+#
+#    <iframe width="560" height="315" 
+#            src="https://www.youtube.com/embed/MHEUQpVeSoQ" 
+#            title="YouTube video player" 
+#            frameborder="0" 
+#            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
+#            allowfullscreen>
+#    </iframe>
+
+
 # Display the result in 3d
 gpv.plot_3d(geo_model, show_lith=True, show_boundaries=True, ve=None)
 
@@ -223,6 +235,19 @@
 # Video tutorial 7: Topography
 # """""""""""""""""""""""""""""""
 
+
+# %%
+#.. raw:: html
+#
+#    <iframe width="560" height="315" 
+#            src="https://www.youtube.com/embed/FtAbUhwhiXE" 
+#            title="YouTube video player" 
+#            frameborder="0" 
+#            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
+#            allowfullscreen>
+#    </iframe>
+
+
 # Setting a randomly generated topography
 import numpy as np
 
