Merge pull request #48 from NREL/pp/separate_param_doc

Separate param docs

examples/example_users.rst

@@ -846,11 +846,11 @@ combinations into multiple sets in our batch config:
         "sets": [
             {
                 "args": {
-                    "wind_turbine_hub_ht": [100],
+                    "wind_turbine_hub_ht": [110],
                     "wind_turbine_rotor_diameter": [145, 170]
                 },
                 "files": ["./turbine.json"],
-                "set_tag": "100hh"
+                "set_tag": "110hh"
             },
             {
                 "args": {
@@ -869,7 +869,7 @@ Now if we run batch (``--dry``), we will only get three sub-directories, which i
     shell
 
     $ ls
-    100hh_wtrd145  100hh_wtrd170  120hh_wtrd160  batch_jobs.csv  config_batch.json  config_gen.json  config_pipeline.json  turbine.json
+    110hh_wtrd145  110hh_wtrd170  120hh_wtrd160  batch_jobs.csv  config_batch.json  config_gen.json  config_pipeline.json  turbine.json
 
 Note how we used the ``"set_tag"`` key to get consistent names across the newly-created runs. Once again,
 we can verify that batch correctly updated the parameters in each sub-directory:
@@ -878,21 +878,21 @@ we can verify that batch correctly updated the parameters in each sub-directory:
 .. code-block::
     shell
 
-    $ cat 100hh_wtrd145/turbine.json
+    $ cat 110hh_wtrd145/turbine.json
     {
         ...
         "wind_turbine_rotor_diameter": 145,
         ...
-        "wind_turbine_hub_ht": 100,
+        "wind_turbine_hub_ht": 110,
         ...
     }
 
-    $ cat 100hh_wtrd170/turbine.json
+    $ cat 110hh_wtrd170/turbine.json
     {
         ...
         "wind_turbine_rotor_diameter": 170,
         ...
-        "wind_turbine_hub_ht": 100,
+        "wind_turbine_hub_ht": 110,
         ...
     }
 

gaps/cli/documentation.py

@@ -501,22 +501,34 @@ def template_config(self):
         )
         return config
 
+    @property
+    def _parameter_npd(self):
+        """NumpyDocString: Parameter help `NumpyDocString` instance."""
+        param_doc = NumpyDocString("")
+        param_doc["Parameters"] = [
+            p
+            for doc in self.docs
+            for p in doc["Parameters"]
+            if p.name in self.template_config
+        ]
+        return param_doc
+
     @property
     def parameter_help(self):
+        """str: Parameter help for the func."""
+        return str(self._parameter_npd)
+
+    @property
+    def hpc_parameter_help(self):
         """str: Parameter help for the func, including execution control."""
         exec_dict_param = [
             p
             for p in NumpyDocString(self.exec_control_doc)["Parameters"]
             if p.name in {"execution_control", "log_directory", "log_level"}
         ]
-        param_only_doc = NumpyDocString("")
-        param_only_doc["Parameters"] = exec_dict_param + [
-            p
-            for doc in self.docs
-            for p in doc["Parameters"]
-            if p.name in self.template_config
-        ]
-        return "\n".join(_format_lines(str(param_only_doc).split("\n")))
+        param_doc = deepcopy(self._parameter_npd)
+        param_doc["Parameters"] = exec_dict_param + param_doc["Parameters"]
+        return "\n".join(_format_lines(str(param_doc).split("\n")))
 
     @property
     def extended_summary(self):
@@ -557,7 +569,7 @@ def config_help(self, command_name):
         doc = CONFIG_DOC.format(
             name=command_name,
             sample_config=sample_config,
-            docstring=self.parameter_help,
+            docstring=self.hpc_parameter_help,
         )
         return _cli_formatted(doc)
 

gaps/version.py

@@ -1,3 +1,3 @@
 """GAPs Version Number. """
 
-__version__ = "0.6.11"
+__version__ = "0.6.12"

requirements.txt

@@ -1,7 +1,7 @@
 click>=8.1.3
 colorama>=0.4.6
 NREL-rex>=0.2.80
-numpy>=1.22.0
+numpy>=1.20,<2.0
 numpydoc>=1.5.0
 pandas>=2.0.0
 psutil>=5.9.2

tests/cli/test_cli_config.py

@@ -1113,13 +1113,13 @@ def test_command_skip_doc_params(test_class):
             skip_doc_params={"input1"},
         )
 
-    assert "input1" not in command_config.documentation.parameter_help
+    assert "input1" not in command_config.documentation.hpc_parameter_help
     assert "input1" not in command_config.documentation.template_config
 
-    assert "_input2" not in command_config.documentation.parameter_help
+    assert "_input2" not in command_config.documentation.hpc_parameter_help
     assert "_input2" not in command_config.documentation.template_config
 
-    assert "input3" in command_config.documentation.parameter_help
+    assert "input3" in command_config.documentation.hpc_parameter_help
     assert "input3" in command_config.documentation.template_config
 
 

tests/cli/test_cli_documentation.py

@@ -250,16 +250,16 @@ def test_command_documentation_default_exec_values_and_doc():
     """Test `CommandDocumentation.default_exec_values` and docs."""
 
     doc = CommandDocumentation(func_no_args)
-    assert "nodes" not in doc.default_exec_values
-    assert "max_workers" not in doc.default_exec_values
-    assert "nodes" not in doc.exec_control_doc
-    assert "max_workers" not in doc.exec_control_doc
+    assert ":nodes:" not in doc.default_exec_values
+    assert ":max_workers:" not in doc.default_exec_values
+    assert ":nodes:" not in doc.exec_control_doc
+    assert ":max_workers:" not in doc.exec_control_doc
 
     doc = CommandDocumentation(func_no_args, is_split_spatially=True)
     assert doc.default_exec_values == DEFAULT_EXEC_VALUES
-    assert "max_workers" not in doc.default_exec_values
-    assert "nodes" in doc.exec_control_doc
-    assert "max_workers" not in doc.exec_control_doc
+    assert ":max_workers:" not in doc.default_exec_values
+    assert ":nodes:" in doc.exec_control_doc
+    assert ":max_workers:" not in doc.exec_control_doc
 
 
 def test_command_documentation_required_args():
@@ -347,6 +347,34 @@ def func(project_points):
     doc = CommandDocumentation(func, is_split_spatially=True)
     param_help = doc.parameter_help
 
+    section_dividers = [
+        any(line) and all(c == "-" for c in line)
+        for line in param_help.split("\n")
+    ]
+    assert sum(section_dividers) == 1
+    assert "Parameters" in param_help
+    assert "project_points" in param_help
+    assert "Path to project points file." in param_help
+    assert "execution_control :" not in param_help
+    assert "log_directory :" not in param_help
+    assert "log_level :" not in param_help
+
+
+def test_command_documentation_hpc_parameter_help():
+    """Test `CommandDocumentation.hpc_parameter_help`."""
+
+    def func(project_points):
+        """Test func.
+
+        Parameters
+        ----------
+        project_points : str
+            Path to project points file.
+        """
+
+    doc = CommandDocumentation(func, is_split_spatially=True)
+    param_help = doc.hpc_parameter_help
+
     section_dividers = [
         any(line) and all(c == "-" for c in line)
         for line in param_help.split("\n")
@@ -397,7 +425,7 @@ def test_command_documentation_config_help(monkeypatch):
 
     assert "my_command_name" in config_help
     assert (
-        gaps.cli.documentation._cli_formatted(doc.parameter_help)
+        gaps.cli.documentation._cli_formatted(doc.hpc_parameter_help)
         in config_help
     )
     assert ".. tabs::" in config_help
@@ -458,7 +486,7 @@ def _func2(another_param, d=42, e=None):
     }
     assert doc.template_config == expected_config
 
-    docstring = doc.parameter_help
+    docstring = doc.hpc_parameter_help
     assert "Max num workers" in docstring
     assert "Path to project points." in docstring
     assert "More input" in docstring
@@ -481,7 +509,7 @@ def _func(another_param, d=42, e=None):
     )
     assert len(doc.signatures) == 1
 
-    docstring = doc.parameter_help
+    docstring = doc.hpc_parameter_help
     assert "Max num workers" not in docstring
     assert "another_param :" not in docstring
     assert "d :" not in docstring
@@ -491,7 +519,7 @@ def _func(another_param, d=42, e=None):
 
 
 def test_command_documentation_for_class():
-    """Test `CommandDocumentation` with func missing docstring."""
+    """Test `CommandDocumentation` for a mix of classes and functions."""
 
     class TestCommand:
         """A test command as a class."""
@@ -556,7 +584,7 @@ def preprocessor(another_input, _a_private_input, another_input2=None):
     )
     assert len(doc.signatures) == 3
 
-    docstring = doc.parameter_help
+    docstring = doc.hpc_parameter_help
     assert ":max_workers:" in docstring
     assert "\narg1 :" in docstring
     assert "\narg2 :" in docstring

tests/test_collection.py

@@ -103,7 +103,7 @@ def make_fake_h5_chunks(temp_dir, features, shuffle=False):
     """
     data = np.random.uniform(0, 20, (50, 50, 48))
     lon, lat = np.meshgrid(np.linspace(-180, 0, 50), np.linspace(90, 0, 50))
-    gids = np.arange(np.product(lat.shape))
+    gids = np.arange(np.prod(lat.shape))
     if shuffle:
         np.random.shuffle(gids)