Updates to docs

docs/src/index.md

@@ -8,17 +8,77 @@ Documentation for [GeoEnergyIO](https://github.com/sintefmath/GeoEnergyIO.jl).
 
 ## Parsing of simulation cases
 
+The main feature of this module is at the time of writing a parser for .DATA reservoir simulation cases. The format originated with the Eclipse reservoir simulator produced by SLB and is now used by many reservoir simulators. The most useful publicly available description of one such dialect is found in the [OPM Flow manual](https://opm-project.org/?page_id=955).
+
 ```@docs
 parse_data_file
 ```
 
 ## Parsing and processing of corner-point grids
 
+Corner-point meshes are the de-facto standard format for simulation of subsurface flow. These meshes are semi-structured, but can have quite complex structure in practice due to eroded and collapsed cells and the presence of faults. This module includes a processor to convert the input format into a mesh that can be used for simulation. Converting the corner-points into a mesh with a connected topology is non-trivial, but the included algorithm has been verified on a number of real-field assets.
+
+There are two main functions to parse and process corner-point inputs:
+
 ```@docs
 parse_grdecl_file
 mesh_from_grid_section
 ```
 
+### Example corner point meshes
+
+The module ships with several corner point grids suitable for testing. These include partially collapsed cells, faults and other degenerate cases that the parser should be able to handle. We can make a few plots of such test grids. The first example is a single hexahedral cell:
+
+```@example
+using GeoEnergyIO, Jutul, CairoMakie
+pth = GeoEnergyIO.test_input_file_path("grdecl", "1cell.txt", base = missing)
+grdecl = parse_grdecl_file(pth)
+g = mesh_from_grid_section(grdecl)
+fig, ax, plt = plot_mesh(g, shading = false, rasterize = true)
+Jutul.plot_mesh_edges!(ax, g)
+fig
+```
+
+To understand a bit more of how this format behaves in practice, we can look at a faulted mesh:
+
+```@example
+using GeoEnergyIO, Jutul, CairoMakie
+pth = GeoEnergyIO.test_input_file_path("grdecl", "raised_col_sloped.txt", base = missing)
+grdecl = parse_grdecl_file(pth)
+g = mesh_from_grid_section(grdecl)
+fig, ax, plt = plot_mesh(g, shading = NoShading, rasterize = true)
+Jutul.plot_mesh_edges!(ax, g)
+fig
+```
+
+More complicated meshes include multiple faults. One synthetic test model is the `model3` case from [MRST](https://www.mrst.no):
+
+```@example
+using GeoEnergyIO, Jutul, CairoMakie
+pth = GeoEnergyIO.test_input_file_path("grdecl", "model3_5_5_5.txt", base = missing)
+grdecl = parse_grdecl_file(pth)
+g = mesh_from_grid_section(grdecl)
+ix = 1:number_of_cells(g)
+fig = Figure()
+ax = Axis3(fig[1,1], zreversed = true, azimuth = 2.0)
+plot_cell_data!(ax, g, ix, shading = NoShading, rasterize = true, colormap = :seaborn_icefire_gradient)
+fig
+```
+
+We can also parse a high-resolution version of the same case:
+
+```@example
+using GeoEnergyIO, Jutul, CairoMakie
+pth = GeoEnergyIO.test_input_file_path("grdecl", "model3_20_20_50.txt", base = missing)
+grdecl = parse_grdecl_file(pth)
+g = mesh_from_grid_section(grdecl)
+ix = 1:number_of_cells(g)
+fig = Figure()
+ax = Axis3(fig[1,1], zreversed = true, azimuth = 2.0)
+plot_cell_data!(ax, g, ix, shading = NoShading, rasterize = true, colormap = :seaborn_icefire_gradient)
+fig
+```
+
 ## Utilities
 
 ```@docs

src/CornerPointGrid/interface.jl

@@ -1,7 +1,17 @@
 """
     mesh_from_grid_section(f, actnum = missing)
 
-TBW
+Generate a Jutul unstructured mesh from a grid section. The input arugment `f`
+can be one of the following:
+
+ - An already parsed complete data file read using [`parse_data_file`](@ref).
+   The "GRID" field will be used.
+ - A parsed "GRID" section from [`parse_grdecl_file`](@ref).
+ - The file-name of a `.GRDECL` file to be parsed before processing.
+
+Optionally the `actnum` can be specified separately. The `actnum` should have
+equal length to the number of logical cells in the grid with true/false
+indicating if a cell is to be included in the processed mesh.
 """
 function mesh_from_grid_section(f, actnum = missing)
     if f isa String

src/InputParser/utils.jl

@@ -494,7 +494,11 @@ end
 """
     number_of_tables(outer_data, t::Symbol)
 
-Number of tables for given type `t`: one of `:satnum`, `:pvtnum` or `:eqlnum`.
+Number of declared tables for given type `t`. Should be one of the following:
+ - `:satnum` (saturation function region)
+ - `:pvtnum` (PVT function region)
+ - `:eqlnum` (equilibriation region)
+ - `:eosnum` (equation-of-state region)
 """
 function number_of_tables(outer_data, t::Symbol)
     rs = outer_data["RUNSPEC"]