More docstring updates, fix broken rst links

Add docutils func that adds a reference to the relative
__init__.py of all files __doc__ in each submodule

change sphinx configuration to be nitpicky which revealed a bunch
of broken sphinx links which were then fixed (except ax and
botorch links which can't be fixed right now because
they don't build sphinx in a normal way.
see facebook/Ax#1227
and see pytorch/botorch#1464
for more info on when ax and botroch can be linked).

Add more docstrings

boa/__init__.py

@@ -10,6 +10,7 @@
     __version__ = "0.0.0"
 
 from boa.ax_instantiation_utils import *  # noqa
+from boa.controller import *  # noqa
 from boa.instantiation_base import *  # noqa
 from boa.metrics.modular_metric import *  # noqa
 from boa.runner import *  # noqa

boa/_doc_utils.py

@@ -1,26 +1,29 @@
-import inspect
-from pathlib import Path
+import importlib
+import pkgutil
 
-FILENAME = Path(__file__).name
+import boa
 
 
-def get_calling_file_path():
-    frames = inspect.stack()
-    frame = 1
-    while (file_path := Path(frames[frame].filename)).name == FILENAME:
-        frame += 1
-    return file_path
+def get_boa_submodules():
+    print(boa)
+    module_list = []
+    packages = []
+    for module_finder, modname, is_pkg in pkgutil.walk_packages(boa.__path__):
+        if is_pkg:
+            packages.append(modname)
+        if len(modname.split(".")) > 1:
+            module_list.append(modname)
+    return module_list
 
 
-def add_ref_to_rel_init():
-    file_path = get_calling_file_path()
+def import_boa_submod(submod_str):
+    return importlib.import_module(f"boa.{submod_str}")
 
-    parent = file_path.parent
-    pathing_ls = []
-    for part in reversed(parent.parts):
-        pathing_ls.append(part)
-        if part == "boa":
-            break
-    pathing = ".".join(module for module in reversed(pathing_ls))
 
-    return f"""**See More Information Here**: :mod:`{pathing}`"""
+def add_ref_to_all_submodules_inits():
+    module_list = get_boa_submodules()
+    for mod_str in module_list:
+        submod = import_boa_submod(mod_str)
+        info = f"""**Overview Information Here**: :mod:`{submod.__package__}`"""
+
+        submod.__doc__ = f"{submod.__doc__}\n\n{info}" if submod.__doc__ else info

boa/ax_instantiation_utils.py

@@ -1,3 +1,12 @@
+"""
+###################################
+Ax Instantiation Utility Functions
+###################################
+
+Utility functions to instantiate Ax objects
+
+"""
+
 from __future__ import annotations
 
 import copy

boa/controller.py

@@ -1,15 +1,23 @@
+"""
+###################################
+Controller
+###################################
+
+"""
+
+
 import logging
 import os
 import time
 from pathlib import Path
 
 from ax.service.scheduler import Scheduler
 
-from boa import BaseWrapper
 from boa.ax_instantiation_utils import get_experiment, get_scheduler
 from boa.runner import WrappedJobRunner
 from boa.storage import scheduler_to_json_file
 from boa.utils import get_dictionary_from_callable
+from boa.wrappers.wrapper import BaseWrapper
 from boa.wrappers.wrapper_utils import get_dt_now_as_str
 
 

boa/metaclasses.py

@@ -1,3 +1,14 @@
+"""
+########################
+Meta Classes
+########################
+
+Meta class modify class behaviors, such as having all subclasses of
+:class:`.BaseWrapper` will wrap functions in :func:`.cd_and_cd_back_dec`
+to make sure whatever directory changes users do inside a wrapper function,
+the directory is returned afterwards.
+
+"""
 import logging
 import traceback
 from abc import ABCMeta

boa/metrics/__init__.py

@@ -1,8 +1,4 @@
-def foo():
-    return "hi"
-
-
-__doc__ = f"""
+"""
 ################################################
 Metrics Overview & Advanced Usage
 ################################################
@@ -17,8 +13,6 @@ def foo():
 
 See :doc:`/user_guide/configuration`
 
-
-{foo()}
 """
 
 from boa.metrics.metrics import *  # noqa

boa/metrics/metric_funcs.py

@@ -1,10 +1,18 @@
+"""
+########################
+Metric Functions
+########################
+
+Functions used for Metrics
+
+"""
+
 import logging
 
 import numpy as np
 import scipy.stats as stats
 from sklearn.metrics import mean_squared_error
 
-from boa._doc_utils import add_ref_to_rel_init
 from boa.utils import get_dictionary_from_callable
 
 logger = logging.getLogger(__name__)
@@ -15,10 +23,12 @@ def normalized_root_mean_squared_error(y_true, y_pred, normalizer="iqr", **kwarg
 
     Parameters
     ----------
-    y_true : array-like of shape (n_samples,) or (n_samples, n_outputs)
+    y_true : array_like
+        With shape (n_samples,) or (n_samples, n_outputs)
         Ground truth (correct) target values.
 
-    y_pred : array-like of shape (n_samples,) or (n_samples, n_outputs)
+    y_pred : array_like
+        With shape (n_samples,) or (n_samples, n_outputs)
         Estimated target values.
 
     normalizer : str
@@ -30,7 +40,7 @@ def normalized_root_mean_squared_error(y_true, y_pred, normalizer="iqr", **kwarg
 
     Returns
     -------
-    nrmse : float or ndarray of floats
+    nrmse : float or numpy.ndarray[float]
         A normalized version of RMSE
     """
     rmse = mean_squared_error(y_true, y_pred, squared=False, **get_dictionary_from_callable(mean_squared_error, kwargs))
@@ -47,14 +57,3 @@ def normalized_root_mean_squared_error(y_true, y_pred, normalizer="iqr", **kwarg
 
     nrmse = rmse / norm
     return nrmse
-
-
-__doc__ = f"""
-########################
-Metric Functions
-########################
-
-Functions used for Metrics
-
-{add_ref_to_rel_init()}
-"""

boa/metrics/metrics.py

@@ -1,6 +1,40 @@
+"""
+########################
+List of Metrics
+########################
+
+List of Metrics that are already defined in BOA
+
+Any of these Metrics can be used directly in your configuration file
+
+Examples
+========
+..  code-block:: YAML
+
+    # Single objective optimization config
+    optimization_options:
+        objective_options:
+            objectives:
+                # List all of your metrics here,
+                # only list 1 metric for a single objective optimization
+                - metric: RootMeanSquaredError
+
+..  code-block:: YAML
+
+    # MultiObjective Optimization config
+    optimization_options:
+        objective_options:
+            objectives:
+                # List all of your metrics here,
+                # only list multiple objectives for a multi objective optimization
+                - metric: RMSE
+                - metric: R2
+
+"""
+
+
 import numpy as np
 
-from boa._doc_utils import add_ref_to_rel_init
 from boa.metrics.metric_funcs import (
     normalized_root_mean_squared_error as normalized_root_mean_squared_error_,
 )
@@ -148,39 +182,3 @@ def __init__(self, metric_to_eval=normalized_root_mean_squared_error_, lower_is_
 
 NRMSE = NormalizedRootMeanSquaredError
 normalized_root_mean_squared_error = NormalizedRootMeanSquaredError
-
-
-__doc__ = f"""
-########################
-List of Metrics
-########################
-
-List of Metrics that are already defined in BOA
-
-Any of these Metrics can be used directly in your configuration file
-
-Examples
-========
-..  code-block:: YAML
-
-    # Single objective optimization config
-    optimization_options:
-        objective_options:
-            objectives:
-                # List all of your metrics here,
-                # only list 1 metric for a single objective optimization
-                - metric: RootMeanSquaredError
-
-..  code-block:: YAML
-
-    # MultiObjective Optimization config
-    optimization_options:
-        objective_options:
-            objectives:
-                # List all of your metrics here,
-                # only list multiple objectives for a multi objective optimization
-                - metric: RMSE
-                - metric: R2
-
-{add_ref_to_rel_init()}
-"""

boa/metrics/modular_metric.py

@@ -1,3 +1,10 @@
+"""
+########################
+Modular Metric
+########################
+
+"""
+
 from __future__ import annotations
 
 import logging
@@ -16,7 +23,6 @@
 from sklearn.metrics import __all__ as sklearn_all
 
 import boa.metrics.synthetic_funcs
-from boa._doc_utils import add_ref_to_rel_init
 from boa.metaclasses import MetricRegister
 from boa.utils import (
     extract_init_args,
@@ -155,8 +161,8 @@ class ModularMetric(NoisyFunctionMetric, metaclass=MetricRegister):
     ``metric_to_eval``.
 
     You can further customize the behavior of your metric by passing a
-    :class:`Wrapper<boa.wrapper.BaseWrapper>`, which has will run methods
-    such as  :meth:`~boa.wrapper.BaseWrapper.fetch_trial_data` before
+    :class:`Wrapper<.BaseWrapper>`, which has will run methods
+    such as  :meth:`~.BaseWrapper.fetch_trial_data` before
     calling the specified metric to evaluate, which can allow you
     to preprocess/prepare model output data for your metric calculation.
 
@@ -320,12 +326,3 @@ def __repr__(self) -> str:
 
         arg_str = " ".join(f"{k}={v}" for k, v in init_dict.items())
         return f"{self.__class__.__name__}({arg_str})"
-
-
-__doc__ = f"""
-########################
-Modular Metric
-########################
-
-{add_ref_to_rel_init()}
-"""

boa/metrics/synthetic_funcs.py

@@ -1,9 +1,14 @@
+"""
+########################
+Synthetic Function
+########################
+
+"""
+
 from ax.utils.measurement.synthetic_functions import from_botorch
 from botorch.test_functions.synthetic import Hartmann
 from torch import Tensor
 
-from boa._doc_utils import add_ref_to_rel_init
-
 
 class Hartmann4(Hartmann):
     dim = 4
@@ -23,12 +28,3 @@ def optimizers(self) -> Tensor:
 
 
 hartmann4 = from_botorch(Hartmann4())
-
-
-__doc__ = f"""
-########################
-Synthetic Function
-########################
-
-{add_ref_to_rel_init()}
-"""

boa/runner.py

@@ -1,3 +1,12 @@
+"""
+###################################
+Wrapped Runner
+###################################
+
+Runner that calls your :mod:`.wrappers` to run your model and poll the trial status.
+
+"""
+
 from collections import defaultdict
 from typing import Any, Dict, Iterable, Set
 

boa/storage.py

@@ -1,3 +1,13 @@
+"""
+########################
+Saving and Loading
+########################
+
+Functions for saving and loading your experiment to
+stop and restart.
+
+"""
+
 import json
 import logging
 import os

boa/utils.py

@@ -1,3 +1,13 @@
+"""
+###################################
+General Package Utility Functions
+###################################
+
+Utility functions useful for various package things like
+getting the signature matching
+
+"""
+
 from __future__ import annotations
 
 import inspect