update sphinx configuration and docs

docs/conf.py

@@ -32,10 +32,13 @@
 PROJECT = 'Yam'
 DESC = 'Yet another monitoring tool using correlations of ambient noise'
 AUTHOR = 'Tom Eulenfeld'
-YEAR = '2017'
+YEAR = '2017-2024'
 GITHUB = 'https://github.com/trichter/yam'
 
 
+autodoc_mock_imports = ['h5py', 'obspyh5', 'tqdm', 'obspy']
+
+
 class Mock(object):
     def __init__(self, *args, **kwargs):
         pass
@@ -62,6 +65,7 @@ def __getitem__(cls, name):
 for i in range(20):
     try:
         import yam
+        import yam.io
         import yam.imaging
     except ImportError:
         exc_type, exc_value, tb = sys.exc_info()
@@ -91,7 +95,10 @@ def __getitem__(cls, name):
               'sphinx.ext.viewcode'
               ]
 
-autodoc_default_flags = ['members']
+autodoc_default_options = {
+    'members': True,
+    'private-members': '_stretch_wrapper, _stack_wrapper',
+}
 default_role = 'py:obj'
 
 # Add any paths that contain templates here, relative to this directory.
@@ -123,11 +130,6 @@ def __getitem__(cls, name):
 # The short X.Y version.
 version = release.split("-")[0]
 
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''

yam/__init__.py

@@ -155,7 +155,7 @@
 Read correlation and results of stretching procedure in Python for further processing
 *************************************************************************************
 
-Use ObsPy's |read| to read correlations and stacks and `~yam.commands.read_dicts()` to read stretching results.
+Use ObsPy's |read| to read correlations and stacks and :func:`~yam.io.read_dicts()` to read stretching results.
 
 ::
 
@@ -186,8 +186,8 @@
 ========================  ========================================
     io                    Configuration for input and output (needed by most functions in `~yam.commands` module)
     correlate             `~yam.commands.start_correlate` -> `~yam.correlate.correlate`  ->  `~yam.correlate.preprocess`  -> `~yam.correlate.time_norm`, `~yam.correlate.spectral_whitening`
-    stack                 `~yam.commands.start_stack` -> `~yam.stack.stack`
-    stretch               `~yam.commands.start_stretch` -> `~yam.commands.stretch_wrapper` -> `~yam.stretch.stretch`
+    stack                 `~yam.commands.start_stack` -> `~yam.commands._stack_wrapper` -> `~yam.stack.stack`
+    stretch               `~yam.commands.start_stretch` -> `~yam.commands._stretch_wrapper` -> `~yam.stretch.stretch`
     plot_*_options        See corresponding functions in `~yam.imaging` module
 ========================  ========================================
 
@@ -211,4 +211,4 @@
 __version__ = '0.7.2'
 
 from yam.main import run
-from yam.commands import read_dicts
+from yam.io import read_dicts

yam/commands.py

@@ -55,7 +55,7 @@ def start_correlate(io,
     :param filter_inventory: filter inventory with its select method,
         specified dict is passed to |Inventory.select|
     :param str startdate,enddate: start and end date as strings
-    : param njobs: number of cores to use for computation, days are computed
+    :param njobs: number of cores to use for computation, days are computed
         parallel, this might consume much memory, default: None -- use all
         available cores, set njobs to 0 for sequential processing
     :param parallel_inner_loop: Run inner loops parallel instead of outer loop
@@ -66,9 +66,9 @@ def start_correlate(io,
         (default: float16 - half precision)
     :param dataset_kwargs: options passed to obspyh5 resp. h5py when creating
          a new dataset,
-         e.g. `dataset_kwargs={'compression':'gzip'}`.
+         e.g. ``dataset_kwargs={'compression':'gzip'}``.
          See create_dataset in h5py for more options.
-         By default the dtype is set to `'float16'`.
+         By default the dtype is set to ``'float16'``.
     :param keep_correlations,stack,\*\*kwargs: all other kwargs are passed to
         `~yam.correlate.correlate()` function
     """
@@ -150,9 +150,9 @@ def start_stack(io, key, outkey, subkey='', njobs=None,
     :param starttime,endtime: constrain start and end dates
     :param dataset_kwargs: options passed to obspyh5 resp. h5py when creating
          a new dataset,
-         e.g. `dataset_kwargs={'compression':'gzip'}`.
+         e.g. ``dataset_kwargs={'compression':'gzip'}``.
          See create_dataset in h5py for more options.
-         By default the dtype is set to `'float16'`.
+         By default the dtype is set to ``'float16'``.
     :param \*\*kwargs: all other kwargs are passed to
         `yam.stack.stack()` function
     """
@@ -270,16 +270,16 @@ def start_stretch(io, key, subkey='', njobs=None, reftrid=None,
         default: None -- use all available cores,
         set njobs to 0 for sequential processing
     :param reftrid: Parallel processing is only possible when this parameter
-        is specified. Key to load the reference trace from, e.g. `'c1_s'`,
-        it can be created by a command similar to `yam stack c1 ''`.
+        is specified. Key to load the reference trace from, e.g. ``'c1_s'``,
+        it can be created by a command similar to ``yam stack c1 ''``.
     :param starttime,endtime: constrain start and end dates
     :param dataset_kwargs: options passed to obspyh5 resp. h5py when creating
          a new dataset,
-         e.g. `dataset_kwargs={'compression':'gzip'}`.
+         e.g. ``dataset_kwargs={'compression':'gzip'}``.
          See create_dataset in h5py for more options.
-         By default the dtype is set to `'float16'`.
+         By default the dtype is set to ``'float16'``.
     :param \*\*kwargs: all other kwargs are passed to
-        `stretch_wrapper()` function
+        `~yam.commands._stretch_wrapper()` function
     """
     if dataset_kwargs is None:
         dataset_kwargs = {}