REF: make modellib private + support numpy docstring style in sphinx docs

docs/conf.py

@@ -14,7 +14,9 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "autoapi.extension",
+    "sphinx.ext.intersphinx",  # for links
+    "sphinx.ext.napoleon",  # for google style docstrings
+    "autoapi.extension",  # to document the wsinfer api
 ]
 
 autoapi_type = "python"
@@ -28,9 +30,15 @@
     "special-members",
     "imported-members",
 ]
+autoapi_ignore = ["*cli*"]
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "torch": ("https://pytorch.org/docs/stable", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

tests/test_all.py

@@ -784,7 +784,7 @@ def test_cli_run_from_config(tiff_image: Path, tmp_path: Path):
     ],
 )
 def test_invalid_modeldefs(modeldef, tmp_path: Path):
-    from wsinfer.modellib.models import Weights
+    from wsinfer._modellib.models import Weights
 
     path = tmp_path / "foobar.yaml"
     with open(path, "w") as f:
@@ -795,7 +795,7 @@ def test_invalid_modeldefs(modeldef, tmp_path: Path):
 
 
 def test_model_registration(tmp_path: Path):
-    from wsinfer.modellib import models
+    from wsinfer._modellib import models
 
     # Test that registering duplicate weights will error.
     d = dict(

wsinfer/__init__.py

@@ -1,3 +1,13 @@
+"""WSInfer is a toolkit for fast patch-based inference on whole slide images."""
 
 from . import _version
-__version__ = _version.get_versions()['version']
+from ._modellib.models import get_model_weights  # noqa
+from ._modellib.models import list_all_models_and_weights  # noqa
+from ._modellib.models import register_model_weights  # noqa
+from ._modellib.run_inference import run_inference  # noqa
+from ._modellib.run_inference import WholeSlideImagePatches  # noqa
+from ._modellib.transforms import PatchClassification  # noqa
+
+__version__ = _version.get_versions()["version"]
+
+del _version

wsinfer/modellib/run_inference.py → wsinfer/_modellib/run_inference.py

@@ -5,7 +5,7 @@
 > normalization of the color channels.
 """
 
-import pathlib
+from pathlib import Path
 import typing
 import warnings
 
@@ -25,9 +25,9 @@
     )
 import tqdm
 
-from . import models
+from .models import Weights
 
-PathType = typing.Union[str, pathlib.Path]
+PathType = typing.Union[str, Path]
 
 
 class WholeSlideImageDirectoryNotFound(FileNotFoundError):
@@ -116,8 +116,8 @@ def __init__(
         self.um_px = float(um_px)
         self.transform = transform
 
-        assert pathlib.Path(wsi_path).exists(), "wsi path not found"
-        assert pathlib.Path(patch_path).exists(), "patch path not found"
+        assert Path(wsi_path).exists(), "wsi path not found"
+        assert Path(patch_path).exists(), "patch path not found"
 
         self.tilesource: large_image.tilesource.TileSource = large_image.getTileSource(
             self.wsi_path
@@ -167,7 +167,7 @@ def __getitem__(
 def run_inference(
     wsi_dir: PathType,
     results_dir: PathType,
-    weights: models.Weights,
+    weights: Weights,
     batch_size: int = 32,
     num_workers: int = 0,
 ) -> None:
@@ -180,12 +180,12 @@ def run_inference(
 
     Parameters
     ----------
-    wsi_dir : str or pathlib.Path
+    wsi_dir : str or Path
         Directory containing whole slide images. This directory can *only* contain
         whole slide images. Otherwise, an error will be raised during model inference.
-    results_dir : str or pathlib.Path
+    results_dir : str or Path
         Directory containing results of patching.
-    weights : wsinfer.modellib.models.Weights
+    weights : wsinfer._modellib.models.Weights
         Instance of Weights including the model object and information about how to
         apply the model to new data.
     batch_size : int
@@ -198,13 +198,13 @@ def run_inference(
     None
     """
     # Make sure required directories exist.
-    wsi_dir = pathlib.Path(wsi_dir)
+    wsi_dir = Path(wsi_dir)
     if not wsi_dir.exists():
         raise WholeSlideImageDirectoryNotFound(f"directory not found: {wsi_dir}")
     wsi_paths = list(wsi_dir.glob("*"))
     if not wsi_paths:
         raise WholeSlideImagesNotFound(wsi_dir)
-    results_dir = pathlib.Path(results_dir)
+    results_dir = Path(results_dir)
     if not results_dir.exists():
         raise ResultsDirectoryNotFound(results_dir)
 
@@ -237,7 +237,7 @@ def run_inference(
         print(f" Slide path: {wsi_path}")
         print(f" Patch path: {patch_path}")
 
-        slide_csv_name = pathlib.Path(wsi_path).with_suffix(".csv").name
+        slide_csv_name = Path(wsi_path).with_suffix(".csv").name
         slide_csv = model_output_dir / slide_csv_name
         if slide_csv.exists():
             print("Output CSV exists... skipping.")

wsinfer/modellib/transforms.py → wsinfer/_modellib/transforms.py

@@ -31,6 +31,8 @@
 
 
 class PatchClassification(torch.nn.Module):
+    """Transform module to process RGB patches."""
+
     def __init__(
         self,
         *,

wsinfer/cli/infer.py

@@ -11,8 +11,8 @@
 
 import click
 
-from ..modellib.run_inference import run_inference
-from ..modellib import models
+from .._modellib.run_inference import run_inference
+from .._modellib import models
 from .._patchlib.create_dense_patch_grid import create_grid_and_save_multi_slides
 from .._patchlib.create_patches_fp import create_patches
 

wsinfer/cli/list_models_and_weights.py

@@ -1,6 +1,6 @@
 import click
 
-from ..modellib import models
+from .._modellib import models
 
 
 @click.command()