Merge pull request #45 from Deltares-research/feature/docs

Merge Feature/docs into main
Deltares-research · Dec 19, 2024 · cecaa9d · cecaa9d
2 parents f3c2bcb + 180fb4f
commit cecaa9d
Show file tree

Hide file tree

Showing 81 changed files with 6,808 additions and 1,276 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,31 @@
+name: Publish GeoST GH-pages
+
+on:
+  push:
+    tags: ['*']
+
+permissions: write-all
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+        name: github-pages
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - name: Setup Pixi
+        uses: prefix-dev/[email protected]
+        with: 
+          manifest-path: pyproject.toml
+      - name: Build docs
+        run: pixi run docs
+      - name: Deploy to Github Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build
diff --git a/.gitignore b/.gitignore
@@ -64,6 +64,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api_reference/generated
+docs/jupyter_execute
 
 # PyBuilder
 target/
@@ -107,6 +109,7 @@ ENV/
 *.gml
 *.dbf
 
+!data/*.nc
 
 # data
 #*.xml

diff --git a/data/boreholes_usp.parquet b/data/boreholes_usp.parquet
diff --git a/data/cpts_usp.parquet b/data/cpts_usp.parquet
diff --git a/data/geotop_usp.nc b/data/geotop_usp.nc
diff --git a/docs/_static/cpts_usp.png b/docs/_static/cpts_usp.png
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,26 @@
+html {
+    --pst-font-size-base: 16px;
+    --pst-header-height: 5rem;
+    --pst-header-article-height: calc(var(--pst-header-height) * 2 / 3);
+    --pst-sidebar-secondary: 12rem;
+}
+
+html[data-theme="light"] {
+    --pst-color-primary: rgb(36, 194, 141);
+    --pst-color-secondary: rgb(48, 167, 236);
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: rgb(36, 194, 141);
+    --pst-color-secondary: rgb(48, 167, 236);
+}
+
+.bd-main .bd-content .bd-article-container {
+    max-width: 90%;
+    /* default is 60em */
+}
+
+.bd-page-width {
+    max-width: 80%;
+    /* default is 88rem */
+}
diff --git a/docs/_static/data_to_solution.png b/docs/_static/data_to_solution.png
diff --git a/docs/_static/example_bro_soil.png b/docs/_static/example_bro_soil.png
diff --git a/docs/_static/example_sand_thickness.png b/docs/_static/example_sand_thickness.png
diff --git a/docs/_static/geost_logo.png b/docs/_static/geost_logo.png
diff --git a/docs/_static/hourglass.png b/docs/_static/hourglass.png
diff --git a/docs/_static/object_hierarchy.png b/docs/_static/object_hierarchy.png
diff --git a/docs/_static/object_hierarchy_models.png b/docs/_static/object_hierarchy_models.png
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,47 @@
+# About GeoST
+```{toctree}
+---
+maxdepth: 2
+caption: About
+hidden:
+---
+```
+
+Subsurface data lie at the basis of solving problems on topics of levee safety, stability
+of infrastructure, drinking water extraction, (sand) mining, subsurface energy systems,
+archeology, CO2 storage, subsidence, contamination and the list goes on. Subsurface data is used by experts to advice on solutions, to visualize and explain subsurface data in the context of the above-mentioned topics and most importantly to create tailor-made schematizations of the subsurface that directly serve as an input for calculating and mapping stability, subsidence, groundwater flow, thermal properties, subsurface resources etc. 
+
+These often complex and high-stake problems require good, reproducible and thoroughly
+tested workflows all the way from subsurface data sources (BRO, GDNR, local files) to for
+instance 3D subsurface models. Therefore, Deltares started the development of GeoST as a
+tool to support the use of subsurface data in Python. It provides easy ways to access, work with and combine many different sources of subsurface data by providing frequently used (spatial) selection functionalities, analytical solutions and reading and export methods for industry standard third party software.
+
+As shown in the figure below, it is aimed at bridging the gap between subsurface data sources and all the analyses, visualisation and modelling efforts that follow. Simple visualisations and analyses may directly be used to give expert advice or subsurface data can be used to create more advanced schematizations and models that serve as an input for applied models.
+
+<p align="left">
+    <img src="_static/data_to_solution.png" alt="Data to solution" title="Data to solution" width="1000" />
+</p>
+
+## Design philosophy
+The design GeoST can best be described as an hourglass. At the top of this hourglass are
+the many different sources through which subsurface data are distributed. This information 
+is read, parsed, validated and subsequently stored in standarized data objects (the neck
+of the hourglass). From here the user can apply basic and commonly used functionality on
+the loaded data. Think of making selections, combining data, conversions, slicing operations etc.
+The results can then be exported to various formats and/or be further used in different
+softwares and tools, depending on the task at hand. 
+
+At the basis of the internal data structures lie simple Pandas DataFrames, allowing the 
+more advanced user to go far beyond the standard set of methods that GeoST offers.
+
+<p align="center">
+    <img src="_static/hourglass.png" alt="Data to solution" title="Data to solution" width="500" />
+</p>
+
+## Current development strategy
+GeoST is being developed incrementally based on project needs. This means that every time
+we require certain functionality within a project, we identify which part of this
+functionality is eligible for addition to GeoST. This part is then developed to the high 
+coding, testing and documentation standards that we require for GeoST. This may take more 
+resources at first, but will pay itself of as the developed functionality is reused in
+other projects. 
diff --git a/docs/api/geost.rst b/docs/api/geost.rst
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
diff --git a/docs/api_reference.md b/docs/api_reference.md
@@ -0,0 +1,24 @@
+# API reference
+
+This is the API reference.
+
+```{toctree}
+---
+maxdepth: 2
+---
+
+PointHeader <api_reference/point_header>
+DiscreteData <api_reference/discrete_data>
+LayeredData <api_reference/layered_data>
+BoreholeCollection <api_reference/borehole_collection>
+CptCollection <api_reference/cpt_collection>
+Input/Output <api_reference/io>
+VoxelModel <api_reference/voxelmodel>
+BroApi <api_reference/bro>
+GeoTop <api_reference/bro_geotop>
+GeoTop selection <api_reference/geotop_selection.rst>
+Analysis <api_reference/analysis>
+Utils <api_reference/utils>
+Enums <api_reference/enums>
+```
+
diff --git a/docs/api_reference/analysis.rst b/docs/api_reference/analysis.rst
@@ -0,0 +1,31 @@
+Analysis
+==========
+
+.. currentmodule:: geost.analysis
+
+Boreholes
+-----------
+.. autosummary::
+   :toctree: generated/
+
+   cumulative_thickness
+   find_top_sand
+   layer_top
+   top_of_sand
+
+
+Cpts
+------
+.. autosummary::
+    :toctree: generated/
+
+    interpret_cpt.calc_ic
+    interpret_cpt.calc_lithology
+
+
+Combine
+--------
+.. autosummary::
+    :toctree: generated/
+
+    combine.add_voxelmodel_variable
diff --git a/docs/api_reference/borehole_collection.rst b/docs/api_reference/borehole_collection.rst
@@ -0,0 +1,58 @@
+BoreholeCollection
+==================
+.. currentmodule:: geost.base
+
+Constructor
+-----------
+.. autosummary::
+   :toctree: generated/
+
+   BoreholeCollection
+
+Methods
+-------
+.. autosummary::
+   :toctree: generated/
+
+   BoreholeCollection.add_header_column_to_data
+   BoreholeCollection.change_horizontal_reference
+   BoreholeCollection.change_vertical_reference
+   BoreholeCollection.check_header_to_data_alignment
+   BoreholeCollection.get
+   BoreholeCollection.get_area_labels
+   BoreholeCollection.get_cumulative_thickness
+   BoreholeCollection.get_layer_top
+   BoreholeCollection.reset_header
+   BoreholeCollection.select_by_condition
+   BoreholeCollection.select_by_depth
+   BoreholeCollection.select_by_length
+   BoreholeCollection.select_by_values
+   BoreholeCollection.select_with_lines
+   BoreholeCollection.select_with_points
+   BoreholeCollection.select_within_bbox
+   BoreholeCollection.select_within_polygons
+   BoreholeCollection.slice_by_values
+   BoreholeCollection.slice_depth_interval
+   BoreholeCollection.to_csv
+   BoreholeCollection.to_datafusiontools
+   BoreholeCollection.to_geopackage
+   BoreholeCollection.to_geoparquet
+   BoreholeCollection.to_kingdom
+   BoreholeCollection.to_multiblock
+   BoreholeCollection.to_parquet
+   BoreholeCollection.to_qgis3d
+   BoreholeCollection.to_shape
+   BoreholeCollection.to_vtm
+
+
+Attributes
+----------
+.. autosummary::
+   :toctree: generated/
+
+   BoreholeCollection.data
+   BoreholeCollection.has_inclined
+   BoreholeCollection.header
+   BoreholeCollection.horizontal_reference
+   BoreholeCollection.n_points
+   BoreholeCollection.vertical_reference
diff --git a/docs/api_reference/bro.rst b/docs/api_reference/bro.rst
@@ -0,0 +1,22 @@
+BroApi
+========
+
+.. currentmodule:: geost.bro
+
+Constructor
+------------
+.. autosummary::
+   :toctree: generated/
+
+   BroApi
+
+
+Methods
+--------
+.. autosummary::
+   :toctree: generated/
+
+   BroApi.get_objects
+   BroApi.search_objects_in_bbox
+   BroApi.apis
+   BroApi.document_types
diff --git a/docs/api_reference/bro_geotop.rst b/docs/api_reference/bro_geotop.rst
@@ -0,0 +1,51 @@
+GeoTop
+==========
+.. currentmodule:: geost.bro.bro_geotop
+
+Constructor
+-------------
+.. autosummary::
+   :toctree: generated/
+
+   GeoTop
+   GeoTop.from_netcdf
+   GeoTop.from_opendap
+
+
+Methods
+---------
+.. autosummary::
+   :toctree: generated/
+
+   GeoTop.isel
+   GeoTop.sel
+   GeoTop.select_bottom
+   GeoTop.select_by_values
+   GeoTop.select_surface_level
+   GeoTop.select_top
+   GeoTop.select_with_line
+   GeoTop.select_with_points
+   GeoTop.select_within_bbox
+   GeoTop.select_within_polygons
+   GeoTop.slice_depth_interval
+   GeoTop.zslice_to_tiff
+
+
+Attributes
+------------
+.. autosummary::
+   :toctree: generated/
+
+   GeoTop.crs
+   GeoTop.horizontal_bounds
+   GeoTop.resolution
+   GeoTop.shape
+   GeoTop.sizes
+   GeoTop.variables
+   GeoTop.vertical_bounds
+   GeoTop.xmax
+   GeoTop.xmin
+   GeoTop.ymax
+   GeoTop.ymin
+   GeoTop.zmax
+   GeoTop.zmin