cleaning up readthedocs material

.readthedocs.yml

@@ -1,5 +1,5 @@
 # Note: builds at
-# https://readthedocs.com/projects/tiledb-inc-tiledb-singlecell/builds/
+# https://readthedocs.com/projects/tiledb-inc-tiledb-soma/builds/
 # (permissioned)
 
 # Don't build any extra formats
@@ -25,7 +25,7 @@ build:
   tools:
     python: "3.8"
   commands:
-    # `pip install -e .` or `python setup.py develop` will _not_ let python find the tiledbsc package
+    # `pip install -e .` or `python setup.py develop` will _not_ let python find the tiledbsoma package
     # within sphinx build
     #- apt-get install python3-sphinx
     - python -m pip install -r doc/requirements_doc.txt

apis/python/src/tiledbsoma/__init__.py

@@ -6,6 +6,7 @@
 from .soma_indexed_dataframe import SOMAIndexedDataFrame
 from .soma_measurement import SOMAMeasurement
 from .soma_sparse_nd_array import SOMASparseNdArray
+from .soma_metadata_mapping import SOMAMetadataMapping
 from .tiledb_array import TileDBArray
 from .tiledb_object import TileDBObject
 from .tiledb_platform_config import TileDBPlatformConfig
@@ -24,4 +25,5 @@
     "SOMACollection",
     "SOMAExperiment",
     "SOMAMeasurement",
+    "SOMAMetadataMapping",
 ]

apis/python/src/tiledbsoma/eta.py

@@ -17,8 +17,8 @@ def __init__(self) -> None:
 
     def ingest_and_predict(self, chunk_percent: float, chunk_seconds: float) -> str:
         """
-        Updates from most recent chunk percent-done and chunk completion-seconds, then does a linear regression on all chunks done so far and estimates time to completion.
-        :param chunk_percent: a percent done like 6.1 or 10.3.
+        Updates from most recent chunk percent-done and chunk completion-seconds, then does a linear regression on all chunks done so far and estimates time to completion.  :param chunk_percent: a percent done like 6.1 or 10.3.
+
         :param chunk_seconds: number of seconds it took to do the current chunk operation.
         """
         self._ingest(chunk_percent, chunk_seconds)
@@ -28,10 +28,7 @@ def ingest_and_predict(self, chunk_percent: float, chunk_seconds: float) -> str:
 
     def _ingest(self, chunk_percent: float, chunk_seconds: float) -> None:
         """
-        Takes the current percent done like 10.3 and current chunk seconds like 58.4 and grows an
-        array of percent-dones and cumulative seconds. This means self.chunk_percents is a list of
-        all the chunk_percent arguments from calling _ingest, while each self.chunk_seconds slot is
-        the sum of all previous chunk_seconds arguments from calling _ingest.
+        Takes the current percent done like 10.3 and current chunk seconds like 58.4 and grows an array of percent-dones and cumulative seconds. This means self.chunk_percents is a list of all the chunk_percent arguments from calling _ingest, while each self.chunk_seconds slot is the sum of all previous chunk_seconds arguments from calling _ingest.
         """
         if len(self.chunk_percents) == 0:
             self.chunk_percents = [chunk_percent]
@@ -42,8 +39,7 @@ def _ingest(self, chunk_percent: float, chunk_seconds: float) -> None:
 
     def _predict(self) -> float:
         """
-        Does a linear regression on all chunks done so far and estimates time to completion.
-        Returns ETA seconds as a number.
+        Does a linear regression on all chunks done so far and estimates time to completion.  Returns ETA seconds as a number.
         """
         # Linear regression where x is cumulative seconds and y is percent done.
         x = np.array(self.cumulative_seconds)

apis/python/src/tiledbsoma/factory.py

@@ -32,11 +32,7 @@ def _construct_member(
     ctx: Optional[tiledb.Ctx] = None,
 ) -> MemberType:
     """
-    Solely for the use of `SOMACollection`. In fact this would/should be a method of the
-    `SOMACollection` class, but there are cyclic-module-import issues.  This allows us to examine
-    storage metadata and invoke the appropriate per-type constructor when reading SOMA groups/arrays
-    from storage.
-    See also `_set_object_type_metadata` and `_get_object_type_metadata` within `TileDBObject`.
+    Solely for the use of ``SOMACollection``. In fact this would/should be a method of the ``SOMACollection`` class, but there are cyclic-module-import issues.  This allows us to examine storage metadata and invoke the appropriate per-type constructor when reading SOMA groups/arrays from storage.  See also ``_set_object_type_metadata`` and ``_get_object_type_metadata`` within ``TileDBObject``.
     """
 
     # Get the class name from TileDB storage. At the TileDB level there are just "arrays" and

apis/python/src/tiledbsoma/io.py

@@ -83,7 +83,7 @@ def from_anndata(
     ctx: Optional[tiledb.Ctx] = None,
 ) -> None:
     """
-    Top-level writer method for creating a TileDB group for a `SOMAExperiment` object.
+    Top-level writer method for creating a TileDB group for a ``SOMAExperiment`` object.
     """
 
     # Without _at least_ an index, there is nothing to indicate the dimension indices.
@@ -226,7 +226,6 @@ def to_h5ad(
 ) -> None:
     """
     Converts the experiment group to anndata format and writes it to the specified .h5ad file.
-    As of 2022-05-05 this is an incomplete prototype.
     """
 
     s = util.get_start_stamp()
@@ -264,13 +263,12 @@ def to_anndata(
     ctx: Optional[tiledb.Ctx] = None,
 ) -> ad.AnnData:
     """
-    Converts the experiment group to anndata. Choice of matrix formats is following
-    what we often see in input .h5ad files:
+    Converts the experiment group to anndata. Choice of matrix formats is following what we often see in input .h5ad files:
 
-    * X as `scipy.sparse.csr_matrix`
-    * obs,var as `pandas.dataframe`
-    * obsm,varm arrays as `numpy.ndarray`
-    * obsp,varp arrays as `scipy.sparse.csr_matrix`
+    * X as ``scipy.sparse.csr_matrix``
+    * obs,var as ``pandas.dataframe``
+    * obsm,varm arrays as ``numpy.ndarray``
+    * obsp,varp arrays as ``scipy.sparse.csr_matrix``
     """
 
     s = util.get_start_stamp()

apis/python/src/tiledbsoma/logging.py

@@ -6,42 +6,37 @@
 
 def warning() -> None:
     """
-    Sets `tiledbsoma.logging` to a WARNING level. Use `tiledbsoma.logging.info()` in notebooks to suppress
-    progress indicators for data ingestion.
+    Sets ``tiledbsoma.logging`` to a WARNING level. Use ``tiledbsoma.logging.info()`` in notebooks to suppress progress indicators for data ingestion.
     """
     _set_level(logging.WARNING)
 
 
 def info() -> None:
     """
-    Sets `tiledbsoma.logging` to an INFO level. Use `tiledbsoma.logging.info()` in notebooks to see
-    progress indicators for data ingestion.
+    Sets ``tiledbsoma.logging`` to an INFO level. Use ``tiledbsoma.logging.info()`` in notebooks to see progress indicators for data ingestion.
     """
     _set_level(logging.INFO)
 
 
 def debug() -> None:
     """
-    Sets `tiledbsoma.logging` to an DEBUG level. Use `tiledbsoma.logging.debug()` in notebooks to see more
-    detailed progress indicators for data ingestion.
+    Sets ``tiledbsoma.logging`` to an DEBUG level. Use ``tiledbsoma.logging.debug()`` in notebooks to see more detailed progress indicators for data ingestion.
     """
     _set_level(logging.DEBUG)
 
 
 def _set_level(level: int) -> None:
     logger.setLevel(level)
-    # Without this check, if someone does `tiledbsoma.logging.info()` twice, or
-    # `tiledbsoma.logging.info()` then `tiledbsoma.logging.debug()`, etc., then log messages will appear
+    # Without this check, if someone does ``tiledbsoma.logging.info()`` twice, or
+    # ``tiledbsoma.logging.info()`` then ``tiledbsoma.logging.debug()``, etc., then log messages will appear
     # twice.
     if not logger.hasHandlers():
         logger.addHandler(logging.StreamHandler())
 
 
 def log_io(info_message: Optional[str], debug_message: str) -> None:
     """
-    Data-ingestion timeframes range widely.  Some folks won't want details for smaller uploads; some
-    will want details for larger ones.  For I/O and for I/O only, it's helpful to print a short
-    message at INFO level, or a different, longer message at/beyond DEBUG level.
+    Data-ingestion timeframes range widely.  Some folks won't want details for smaller uploads; some will want details for larger ones.  For I/O and for I/O only, it's helpful to print a short message at INFO level, or a different, longer message at/beyond DEBUG level.
     """
     if logger.level == logging.INFO:
         if info_message is not None: