ENH: add one-liner function for volumetrics export in RMS

docs/rms_oneliners.rst

@@ -0,0 +1,47 @@
+RMS targeted functions
+======================
+
+For lowerering the user threshold, some "one-liner" functions have been made for RMS. The purpose
+is both to make it simpler for users to export certain items, and in addition secure a better
+consistency. Hence the end user is not burdened to provide details, and only a script with quite
+a few lines will be needed.
+
+Currently only volumes are exposed, but this will be extended in the near future.
+
+Exporting volumetrics from RMS
+------------------------------
+
+Volumetrics in RMS is always done in a so-called volume jobs. The intention with the simplification
+is to use the RMS API behind the scene to retrieve all necessary data needed for ``fmu.dataio``.
+
+Example:
+
+.. code-block:: python
+
+    from fmu.dataio.export.rms import export_rms_volumetrics
+    ...
+
+    # here 'Geogrid' is the grid model name, and 'geogrid_volumes' is the name of the volume job
+    outfiles = export_rms_volumetrics(project, "Geogrid", "geogrid_volumes")
+
+    print(f"Output volumes to {outfiles}")
+
+Most ``dataio`` settings are here defaulted, but some keys can be altered optionally, e.g.:
+
+.. code-block:: python
+
+    outfiles = export_rms_volumetrics(
+        project,
+        "Geogrid",
+        "geogrid_volumes",
+        global_variables="../whatever/global_variables.yml",
+        tagname="vol",
+        subfolder="volumes",
+    )
+
+
+Details
+-------
+
+.. automodule:: fmu.dataio.export.rms.volumetrics
+    :members:

docs/src/conf.py

@@ -85,6 +85,14 @@ def filter(self, record: logging.LogRecord) -> bool:
 current_year = date.today().year
 copyright = f"Equinor {current_year} (fmu-dataio release {release})"
 
+
+# Sort members by input order in classes
+autodoc_member_order = "bysource"
+autodoc_default_flags = ["members", "show_inheritance"]
+
+# Mocking ert and RMS modules
+autodoc_mock_imports = ["ert", "rmsapi", "_rmsapi", "roxar", "_roxar"]
+
 exclude_patterns = ["_build"]
 
 pygments_style = "sphinx"

docs/src/index.rst

@@ -40,5 +40,6 @@ post-processing services, new and improved cloud-only version of Webviz and much
    overview
    preparations
    examples
+   rms_oneliners
    apiref/modules
    datamodel/index

src/fmu/dataio/__init__.py

@@ -1,15 +1,24 @@
 """Top-level package for fmu-dataio"""
-# noqa
 
-from fmu.dataio.dataio import AggregatedData  # noqa  # type: ignore
-from fmu.dataio.dataio import ExportData  # noqa  # type: ignore
-from fmu.dataio.dataio import InitializeCase  # noqa  # type: ignore
-from fmu.dataio.dataio import read_metadata  # noqa
-from fmu.dataio.preprocessed import ExportPreprocessedData  # noqa  # type: ignore
+from fmu.dataio.dataio import (
+    AggregatedData,
+    ExportData,
+    InitializeCase,
+    read_metadata,
+)
+from fmu.dataio.preprocessed import ExportPreprocessedData
 
 try:
     from .version import version
 
     __version__ = version
 except ImportError:
     __version__ = "0.0.0"
+
+__all__ = [
+    "AggregatedData",
+    "ExportData",
+    "InitializeCase",
+    "read_metadata",
+    "ExportPreprocessedData",
+]

src/fmu/dataio/export/rms/__init__.py

@@ -0,0 +1,3 @@
+from .volumetrics import export_rms_volumetrics
+
+__all__ = ["export_rms_volumetrics"]

src/fmu/dataio/export/rms/_conditional_rms_imports.py

@@ -0,0 +1,40 @@
+"""Handle rmsapi or roxar (deprecated version of rmsapi); only present inside RMS"""
+import warnings
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+# mypy: ignore-errors
+
+
+def import_rms_package() -> Optional[Dict[str, Any]]:
+    """
+    Attempts to import the 'rmsapi' package first. If 'rmsapi' is not available,
+    it attempts to import the 'roxar' package while suppressing deprecation warnings.
+    Returns a dictionary with the imported modules or raises ImportError if neither
+    is available.
+    """
+    # mypy: ignore-errors
+    try:
+        import rmsapi  # type: ignore[import]
+        import rmsapi.jobs as jobs  # type: ignore[import]
+
+        return {"rmsapi": rmsapi, "jobs": jobs}
+    except ImportError:
+        try:
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore", category=DeprecationWarning, module="roxar"
+                )
+                import roxar as rmsapi  # type: ignore[import]
+                import roxar.jobs as jobs  # type: ignore[import]
+
+                return {"rmsapi": rmsapi, "jobs": jobs}
+        except ImportError:
+            raise ImportError(
+                "Neither 'roxar' nor 'rmsapi' are available. You have to be inside "
+                "RMS to use this function."
+            )
+
+
+if TYPE_CHECKING:
+    import rmsapi  # type: ignore # noqa
+    import rmsapi.jobs  # type: ignore # noqa