CrayLabs · amandarichardsonn · Apr 25, 2024 · Apr 22, 2024 · Apr 22, 2024 · Apr 22, 2024
diff --git a/conftest.py b/conftest.py
@@ -609,11 +609,8 @@ def make_test_file(
         """Create a dummy file in the test output directory.
 
         :param file_name: name of file to create, e.g. "file.txt"
-        :type file_name: str
         :param file_dir: path
-        :type file_dir: str
         :return: String path to test output file
-        :rtype: str
         """
         file_path = os.path.join(file_dir, file_name)
         os.makedirs(file_dir)

diff --git a/doc/api/smartsim_api.rst b/doc/api/smartsim_api.rst
@@ -26,6 +26,7 @@ Experiment
    Experiment.get_status
    Experiment.reconnect_orchestrator
    Experiment.summary
+   Experiment.telemetry
 
 .. autoclass:: Experiment
    :show-inheritance:
@@ -407,6 +408,7 @@ Orchestrator
    Orchestrator.set_max_clients
    Orchestrator.set_max_message_size
    Orchestrator.set_db_conf
+   Orchestrator.telemetry
 
 Orchestrator
 ------------

diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -18,6 +18,7 @@ To be released at some future point in time
 
 Description
 
+- Auto-generate type-hints into documentation
 - Auto-post release PR to develop
 - Bump manifest.json to version 0.0.4
 - Fix symlinking batch ensemble and model bug
@@ -48,6 +49,8 @@ Description
 
 Detailed Notes
 
+- Add extension to auto-generate function type-hints into documentation.
+  (SmartSim-PR561_)
 - Add to github release workflow to auto generate a pull request from master
   into develop for release. (SmartSim-PR566_)
 - The manifest.json version needs to match the SmartDashboard version, which is
@@ -129,6 +132,7 @@ Detailed Notes
   handler. SmartSim will now attempt to kill any launched jobs before calling
   the previously registered signal handler. (SmartSim-PR535_)
 
+.. _SmartSim-PR561: https://github.com/CrayLabs/SmartSim/pull/561
 .. _SmartSim-PR566: https://github.com/CrayLabs/SmartSim/pull/566
 .. _SmartSim-PR563: https://github.com/CrayLabs/SmartSim/pull/563
 .. _SmartSim-PR547: https://github.com/CrayLabs/SmartSim/pull/547

diff --git a/doc/conf.py b/doc/conf.py
@@ -14,6 +14,9 @@
 
 import os
 import sys
+import logging
+import inspect
+from sphinx.util.logging import SphinxLoggerAdapter
 sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
@@ -39,6 +42,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
@@ -56,6 +60,12 @@
     'sphinx_design',
     'sphinx.ext.mathjax',
 ]
+# sphinx_autodoc_typehints configurations
+always_use_bars_union = True
+typehints_document_rtype = True
+typehints_use_signature = True
+typehints_use_signature_return = True
+typehints_defaults = 'comma'
 
 autodoc_mock_imports = ["smartredis.smartredisPy"]
 suppress_warnings = ['autosectionlabel']
@@ -143,4 +153,16 @@ def ensure_pandoc_installed(_):
 
 
 def setup(app):
-    app.connect("builder-inited", ensure_pandoc_installed)
+    app.connect("builder-inited", ensure_pandoc_installed)
+
+    # Below code from https://github.com/sphinx-doc/sphinx/issues/10219
+    def _is_sphinx_logger_adapter(obj):
+        return isinstance(obj, SphinxLoggerAdapter)
+    class ForwardReferenceFilter(logging.Filter):
+        def filter(self, record):
+            # Suppress the warning related to forward references
+            return "Cannot resolve forward reference in type annotations" not in record.getMessage()
+
+    members = inspect.getmembers(app.extensions['sphinx_autodoc_typehints'].module, _is_sphinx_logger_adapter)
+    for _, adapter in members:
+        adapter.logger.addFilter(ForwardReferenceFilter())
diff --git a/doc/requirements-doc.txt b/doc/requirements-doc.txt
@@ -14,3 +14,4 @@ protobuf
 numpy
 sphinx-design
 pypandoc
+sphinx-autodoc-typehints
diff --git a/doc/tutorials/ml_training/surrogate/fd_sim.py b/doc/tutorials/ml_training/surrogate/fd_sim.py
@@ -18,12 +18,9 @@ def augment_batch(samples, targets):
     following NWHC ordering.
 
     :param samples: Samples to augment
-    :type samples: np.ndarray
     :param targets: Targets to augment
-    :type targets: np.ndarray
 
     :returns: Tuple of augmented samples and targets
-    :rtype: (np.ndarray, np.ndarray)
     """
     batch_size = samples.shape[0]
     augmented_samples = np.empty((batch_size*8, *samples.shape[1:]))
@@ -83,9 +80,7 @@ def simulate(steps, size):
     both as tensors and as augmented samples for training.
 
     :param steps: Number of simulations to run
-    :type steps: int
     :param size: lateral size of the discretized domain
-    :type size: int
     """
     batch_size = 50
     samples = np.zeros((batch_size,size,size,1)).astype(np.single)

diff --git a/smartsim/_core/_cli/utils.py b/smartsim/_core/_cli/utils.py
@@ -78,7 +78,6 @@ def clean(core_path: Path, _all: bool = False) -> int:
     """Remove pre existing installations of ML runtimes
 
     :param _all: Remove all non-python dependencies
-    :type _all: bool, optional
     """
 
     build_temp = core_path / ".third-party"

diff --git a/smartsim/_core/_install/builder.py b/smartsim/_core/_install/builder.py
@@ -63,7 +63,6 @@ def expand_exe_path(exe: str) -> str:
     """Takes an executable and returns the full path to that executable
 
     :param exe: executable or file
-    :type exe: str
     :raises TypeError: if file is not an executable
     :raises FileNotFoundError: if executable cannot be found
     """
@@ -283,9 +282,7 @@ def build_from_git(
     ) -> None:
         """Build Redis from git
         :param git_url: url from which to retrieve Redis
-        :type git_url: str
         :param branch: branch to checkout
-        :type branch: str
         """
         # pylint: disable=too-many-locals
         database_name = "keydb" if "KeyDB" in git_url else "redis"
@@ -534,7 +531,6 @@ def symlink_libtf(self, device: Device) -> None:
         """Add symbolic link to available libtensorflow in RedisAI deps.
 
         :param device: cpu or gpu
-        :type device: str
         """
         rai_deps_path = sorted(
             self.rai_build_path.glob(os.path.join("deps", f"*{device.value}*"))
@@ -591,11 +587,8 @@ def build_from_git(
         """Build RedisAI from git
 
         :param git_url: url from which to retrieve RedisAI
-        :type git_url: str
         :param branch: branch to checkout
-        :type branch: str
         :param device: cpu or gpu
-        :type device: str
         """
         # delete previous build dir (should never be there)
         if self.rai_build_path.is_dir():
@@ -705,7 +698,6 @@ def _fetch_deps_for(self, device: Device) -> None:
     def _install_backends(self, device: Device) -> None:
         """Move backend libraries to smartsim/_core/lib/
         :param device: cpu or cpu
-        :type device: str
         """
         self.rai_install_path = self.rai_build_path.joinpath(
             f"install-{device.value}"

diff --git a/smartsim/_core/control/controller.py b/smartsim/_core/control/controller.py
@@ -97,7 +97,6 @@ def __init__(self, launcher: str = "local") -> None:
         """Initialize a Controller
 
         :param launcher: the type of launcher being used
-        :type launcher: str
         """
         self._jobs = JobManager(JM_LOCK)
         self.init_launcher(launcher)
@@ -158,11 +157,8 @@ def poll(
         """Poll running jobs and receive logging output of job status
 
         :param interval: number of seconds to wait before polling again
-        :type interval: int
         :param verbose: set verbosity
-        :type verbose: bool
         :param kill_on_interrupt: flag for killing jobs when SIGINT is received
-        :type kill_on_interrupt: bool, optional
         """
         self._jobs.kill_on_interrupt = kill_on_interrupt
         to_monitor = self._jobs.jobs
@@ -182,7 +178,6 @@ def finished(
         """Return a boolean indicating wether a job has finished or not
 
         :param entity: object launched by SmartSim.
-        :type entity: Entity | EntitySequence
         :returns: bool
         :raises ValueError: if entity has not been launched yet
         """
@@ -212,7 +207,6 @@ def stop_entity(
         the jobmanager so that the job appears as "cancelled".
 
         :param entity: entity to be stopped
-        :type entity: Entity | EntitySequence
         """
         with JM_LOCK:
             job = self._jobs[entity.name]
@@ -235,8 +229,8 @@ def stop_entity(
 
     def stop_db(self, db: Orchestrator) -> None:
         """Stop an orchestrator
+
         :param db: orchestrator to be stopped
-        :type db: Orchestrator
         """
         if db.batch:
             self.stop_entity(db)
@@ -268,7 +262,6 @@ def stop_entity_list(self, entity_list: EntitySequence[SmartSimEntity]) -> None:
         """Stop an instance of an entity list
 
         :param entity_list: entity list to be stopped
-        :type entity_list: EntitySequence
         """
 
         if entity_list.batch:
@@ -291,10 +284,8 @@ def get_entity_status(
         """Get the status of an entity
 
         :param entity: entity to get status of
-        :type entity: SmartSimEntity | EntitySequence
         :raises TypeError: if not SmartSimEntity | EntitySequence
         :return: status of entity
-        :rtype: SmartSimStatus
         """
         if not isinstance(entity, (SmartSimEntity, EntitySequence)):
             raise TypeError(
@@ -310,10 +301,8 @@ def get_entity_list_status(
 
         :param entity_list: entity list containing entities to
                             get statuses of
-        :type entity_list: EntitySequence
         :raises TypeError: if not EntitySequence
         :return: list of SmartSimStatus statuses
-        :rtype: list
         """
         if not isinstance(entity_list, EntitySequence):
             raise TypeError(
@@ -332,7 +321,6 @@ def init_launcher(self, launcher: str) -> None:
         and local launching
 
         :param launcher: which launcher to initialize
-        :type launcher: str
         :raises SSUnsupportedError: if a string is passed that is not
                                     a supported launcher
         :raises TypeError: if no launcher argument is provided.
@@ -364,9 +352,7 @@ def symlink_output_files(
         under the .smartsim directory
 
         :param job_step: Job step instance
-        :type job_step: Step
         :param entity: Entity instance
-        :type entity: SmartSimEntity | EntitySequence[SmartSimEntity]
         """
         historical_out, historical_err = map(pathlib.Path, job_step.get_output_files())
         entity_out = pathlib.Path(entity.path) / f"{entity.name}.out"
@@ -398,11 +384,8 @@ def _launch(
         address of the database can be given to following entities
 
         :param exp_name: The name of the launching experiment
-        :type exp_name: str
         :param exp_path: path to location of ``Experiment`` directory if generated
-        :type exp_path: str
         :param manifest: Manifest of deployables to launch
-        :type manifest: Manifest
         """
 
         manifest_builder = LaunchedManifestBuilder[t.Tuple[str, Step]](
@@ -505,10 +488,8 @@ def _launch_orchestrator(
         set them in the JobManager
 
         :param orchestrator: orchestrator to launch
-        :type orchestrator: Orchestrator
         :param manifest_builder: An `LaunchedManifestBuilder` to record the
                                  names and `Step`s of the launched orchestrator
-        :type manifest_builder: LaunchedManifestBuilder[tuple[str, Step]]
         """
         orchestrator.remove_stale_files()
         orc_telem_dir = manifest_builder.run_telemetry_subdirectory / "database"
@@ -581,9 +562,7 @@ def _launch_step(
         """Use the launcher to launch a job step
 
         :param job_step: a job step instance
-        :type job_step: Step
         :param entity: entity instance
-        :type entity: SmartSimEntity
         :raises SmartSimError: if launch fails
         """
         # attempt to retrieve entity name in JobManager.completed
@@ -641,13 +620,10 @@ def _create_batch_job_step(
         """Use launcher to create batch job step
 
         :param entity_list: EntityList to launch as batch
-        :type entity_list: EntityList
         :param telemetry_dir: Path to a directory in which the batch job step
                               may write telemetry events
-        :type telemetry_dir: pathlib.Path
         :return: batch job step instance and a list of run steps to be
                  executed within the batch job
-        :rtype: tuple[Step, list[Step]]
         """
         if not entity_list.batch_settings:
             raise ValueError(
@@ -676,12 +652,9 @@ def _create_job_step(
         """Create job steps for all entities with the launcher
 
         :param entity: an entity to create a step for
-        :type entity: SmartSimEntity
         :param telemetry_dir: Path to a directory in which the job step
                                may write telemetry events
-        :type telemetry_dir: pathlib.Path
         :return: the job step
-        :rtype: Step
         """
         # get SSDB, SSIN, SSOUT and add to entity run settings
         if isinstance(entity, Model):
@@ -698,7 +671,6 @@ def _prep_entity_client_env(self, entity: Model) -> None:
         """Retrieve all connections registered to this entity
 
         :param entity: The entity to retrieve connections from
-        :type entity:  Model
         """
 
         client_env: t.Dict[str, t.Union[str, int, float, bool]] = {}
@@ -763,7 +735,6 @@ def _save_orchestrator(self, orchestrator: Orchestrator) -> None:
         to the orchestrator.
 
         :param orchestrator: Orchestrator configuration to be saved
-        :type orchestrator: Orchestrator
         """
 
         dat_file = "/".join((orchestrator.path, "smartsim_db.dat"))
@@ -785,7 +756,6 @@ def _orchestrator_launch_wait(self, orchestrator: Orchestrator) -> None:
         be launched with SSDB address
 
         :param orchestrator: orchestrator instance
-        :type orchestrator: Orchestrator
         :raises SmartSimError: if launch fails or manually stopped by user
         """
         if orchestrator.batch:
@@ -934,7 +904,6 @@ def _start_telemetry_monitor(self, exp_dir: str) -> None:
         of the processes launched through this controller.
 
         :param exp_dir: An experiment directory
-        :type exp_dir: str
         """
         if (
             self._telemetry_monitor is None