Add missing docstrings

doc/_templates/footer_start.html

@@ -1,3 +1,3 @@
 {%- if show_copyright %}
-<a href="{{ pathto('about') }}#authors"><i class="far fa-copyright"></i> {{ copyright }} </a>
+<a href="{{ pathto('about/authors') }}"><i class="far fa-copyright"></i> {{ copyright }} </a>
 {%- endif %}

doc/_templates/index.html

@@ -4,14 +4,16 @@
 {% block body %}
 
 <h1 class="display-5">
-  pyGIMLi is an open-source library for multi-method modelling and inversion in geophysics.
+  Open-source multi-method modelling and inversion in geophysics.
 </h1>
-<a class="btn btn-primary btn-lg mt-2" href="{{pathto('about')}}">
-  <i class="fas fa-book me-1"></i> Learn more
-</a>
-<a class="btn btn-success btn-lg mt-2 ms-2 text-white" href="{{pathto('user-guide/getting-started/index')}}">
-  <i class="fas fa-rocket me-1"></i> Getting started
-</a>
+<div class="d-flex flex-column flex-sm-row gap-2 mt-2">
+  <a class="btn btn-primary btn-lg" href="{{pathto('about')}}">
+    <i class="fas fa-book me-1"></i> Learn more
+  </a>
+  <a class="btn btn-success btn-lg text-white" href="{{pathto('user-guide/getting-started/index')}}">
+    <i class="fas fa-rocket me-1"></i> Getting started
+  </a>
+</div>
 
 <h1 class="mt-5">Showcase
   <small class="text-muted">

doc/community/development/index.md

@@ -16,11 +16,11 @@ Coding standards and contribution workflow for pyGIMLi.
 
 How to write and format documentation with Markdown and MyST.
 :::
-:::{grid-item-card} Dependencies
+:::{grid-item-card} Compiling from source
 :link: sec-install-pre
 :link-type: ref
 
-Tools and libraries required to build pyGIMLi from source.
+Tools and dependencies required to compile pyGIMLi from source.
 :::
 ::::
 

doc/conf.py

@@ -93,6 +93,7 @@
     'sphinxcontrib.programoutput',
     "bibtexparser",
     "sphinx_design",
+    "sphinx_copybutton",
     # "sphinx_tippy"
     # "sphinxcontrib.spelling"
     #'sphinx.ext.pngmath',   # for breath

pygimli/core/__init__.py

@@ -884,6 +884,21 @@ def __EQ_RVector__(self, val):
 # useful stuff
 ############################
 def toIVector(v):
+    """Convert an array-like to a pgcore.IVector.
+
+    .. deprecated::
+        Use a plain NumPy integer array instead.  This function will be
+        removed in a future release.
+
+    Parameters
+    ----------
+    v : array-like
+        Values to convert.
+
+    Returns
+    -------
+    pgcore.IVector
+    """
     print("do not use toIVector(v) use ndarray directly .. "
           "this method will be removed soon")
     ret = pgcore.IVector(len(v), 0)

pygimli/core/datacontainer.py

@@ -7,6 +7,7 @@
 
 
 def __DataContainer_str(self):
+    """Return a short human-readable summary of the data container."""
     return "Data: Sensors: " + str(self.sensorCount()) + " data: " + \
         str(self.size()) + ", nonzero entries: " + \
         str([d for d in self.dataMap().keys() if self.isSensorIndex(d) or
@@ -50,6 +51,7 @@ def __DataContainer_setSensors(self, sensors):
 
 
 def __DataContainer_copy(self):
+    """Return a copy of this data container, preserving its concrete type."""
     return type(self)(self)
 
 
@@ -72,6 +74,18 @@ def __DC_setVal(self, key, val):
 
 
 def __DC_getVal(self, key):
+    """Return data values for *key*, as integer array for sensor-index fields.
+
+    Parameters
+    ----------
+    key : str
+        Data token to retrieve.
+
+    Returns
+    -------
+    numpy.ndarray or pg.Vector
+        Integer array for sensor-index tokens, otherwise the raw pg.Vector.
+    """
     if self.isSensorIndex(key):
         return np.array(self(key), dtype=int)
     # return self(key).array() // d['a'][2] = 0.0, would be impossible
@@ -82,6 +96,11 @@ def __DC_getVal(self, key):
 
 
 def __DataContainer_ensure2D(self):
+    """Swap Y and Z coordinates if sensors are arranged in the X-Z plane.
+
+    Corrects sensor positions when data were stored with depth in the Z
+    direction but the 2-D convention requires depth along Y.
+    """
     sen = self.sensors()
     if ((zVari(sen) or max(abs(z(sen))) > 0) and
             (not yVari(sen) and max(abs(y(sen))) < 1e-8)):
@@ -93,6 +112,7 @@ def __DataContainer_ensure2D(self):
 
 
 def __DataContainer_swapXY(self):
+    """Swap X and Y sensor coordinates in-place."""
     sen = self.sensors()
     swapYZ(sen)
     self.setSensorPositions(sen)
@@ -183,6 +203,13 @@ def __DataContainer_getIndices(self, **kwargs):
 
 
 def __DataContainer_removeData(self, **kwargs):
+    """Remove data entries matching all supplied key=value conditions.
+
+    Parameters
+    ----------
+    **kwargs :
+        Token–value pairs; entries for which all conditions hold are removed.
+    """
     self.markInvalid(self.getIndices(**kwargs))
     self.removeInvalid()