New metadocs and initial numpydoc

candle/ckpt_utils.py

@@ -142,21 +142,29 @@ class ParamType(Enum):
     STRING = auto()
     BOOLEAN = auto()
     INTEGER = auto()
-    # integer: non-negative
+    #: integer, non-negative
     INTEGER_NN = auto()
-    # integer: greater-than-zero
+    #: integer, greater-than-zero
     INTEGER_GZ = auto()
     FLOAT = auto()
+    #: float, non-negative
     FLOAT_NN = auto()
 
 
 class CandleCkpt:
-    def __init__(self, gParameters=None, logger: str = "DEFAULT", verbose: bool = True):
+    def __init__(self, gParameters=None, logger: any = "DEFAULT", verbose: bool = True):
         """
-        :param Logger logger: The logger to use.
+        The superclass for the ckpt classes
+
+        Parameters
+        ----------
+        logger : A Logger object or None or "DEFAULT"
+            The logger to use.
             May be None to disable or "DEFAULT" to use the default.
-        :param boolean verbose: If True, more verbose logging
-            Passed to helper_utils.set_up_logger(verbose) for this logger
+        verbose : boolean
+            If True, more verbose logging.
+            Passed to ``helper_utils.set_up_logger()``
+            for the given logger
         """
         self.logger = logger
         if self.logger == "DEFAULT":
@@ -187,7 +195,14 @@ def __init__(self, gParameters=None, logger: str = "DEFAULT", verbose: bool = Tr
         self.report_initial()
 
     def scan_params(self, gParams):
-        """Simply translate gParameters into instance fields"""
+        """Simply translate gParameters into instance fields
+
+        Parameters
+        ----------
+        gParams : dict
+            The CANDLE hyperparameters to apply
+
+        """
         self.gParams = gParams
         self.ckpt_directory = gParams["ckpt_directory"]
         self.epoch_max = self.param("epochs", ParamRequired(), ParamType.INTEGER_NN)

docs/NOTES.txt

@@ -9,16 +9,35 @@ sphinx
 
 pip:
 
+(
 candle
 myst_nb
 sphinx_design
 sphinx_book_theme
+astropy
+matplotlib
 nbsphinx
+numpy
+pandas
+patsy
+scipy
+scikit-learn
+statsmodels
+tensorflow
+torch
+)
 
 Then run:
 
 make html
 
+NOTE:
+You must re-pip-install candle_lib before re-building the docs!
+Sphinx docs are based on the pip-installed copies.
+
+To add a new function:
+Add it to the corresponding api_*/index.rst file
+
 Adding a new example:
 
 1. Add a 00<x-name>.ipynb file to the docs/examples folder

docs/api_ckpt_utils/index.rst

@@ -11,6 +11,7 @@ CKPT_UTILS
    ckpt_utils.CandleCkptModel
    ckpt_utils.ParamType
    ckpt_utils.CandleCkpt
+   ckpt_utils.CandleCkpt.scan_params
    ckpt_utils.ParamRequired
    ckpt_utils.ckpt_parser
    ckpt_utils.ckpt_defs