Merge branch 'develop' into experiment/laghos

docs/conf.py

@@ -7,6 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import subprocess
+import sys
+import os
 
 subprocess.call(
     [
@@ -32,8 +34,12 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinxcontrib.programoutput",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
 ]
 
+sys.path.insert(0, os.path.abspath("../lib"))
+
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".spack-env"]
 
 # -- Options for HTML output -------------------------------------------------

docs/index.rst

@@ -48,6 +48,12 @@
    add-an-experiment
    add-a-dryrun
 
+.. toctree::
+   :maxdepth: 2
+   :caption: API Docs
+
+   Benchpark API Docs <source/benchpark>
+
 .. toctree::
    :maxdepth: 1
    :caption: Legacy Workflow

lib/benchpark/directives.py

@@ -116,8 +116,10 @@ def variant(
     sticky: bool = False,
 ):
     """Define a variant.
+
     Can specify a default value as well as a text description.
-    Args:
+
+    Arguments:
         name: Name of the variant
         default: Default value for the variant, if not specified otherwise the default will be
             False for a boolean variant and 'nothing' for a multi-valued variant
@@ -130,6 +132,7 @@ def variant(
             if the group doesn't meet the additional constraints
         when: Optional condition on which the variant applies
         sticky: The variant should not be changed by the concretizer to find a valid concrete spec
+
     Raises:
         DirectiveError: If arguments passed to the directive are invalid
     """

lib/benchpark/repo.py

@@ -151,7 +151,7 @@ def set_path(repo, object_type=default_type):
 def additional_repository(repository, object_type=default_type):
     """Adds temporarily a repository to the default one.
 
-    Args:
+    Parameters:
         repository: repository to be added
     """
     paths[object_type].put_first(repository)
@@ -163,8 +163,8 @@ def additional_repository(repository, object_type=default_type):
 def use_repositories(*paths_and_repos, object_type=default_type):
     """Use the repositories passed as arguments within the context manager.
 
-    Args:
-        *paths_and_repos: paths to the repositories to be used, or
+    Parameters:
+        `*paths_and_repos`: paths to the repositories to be used, or
             already constructed Repo objects
 
     Returns:

lib/benchpark/spec.py

@@ -623,11 +623,11 @@ def tokens(self) -> List[Token]:
     def next_spec(self) -> Optional[Spec]:
         """Return the next spec parsed from text.
 
-        Args:
+        Parameters:
             initial_spec: object where to parse the spec. If None a new one
                 will be created.
 
-        Return
+        Returns:
             The spec that was parsed
         """
         if not self.ctx.next_token:

lib/benchpark/variant.py

@@ -24,7 +24,7 @@ def __init__(
     ):
         """Initialize a package variant.
 
-        Args:
+        Parameters:
             name (str): name of the variant
             default (str): default value for the variant in case
                 nothing has been specified
@@ -74,12 +74,13 @@ def validate_values(self, variant_values, pkg_cls=None):
         """Validate a variant spec against this package variant. Raises an
         exception if any error is found.
 
-        Args:
+        Parameters:
             vspec_values (tuple): values to be validated
             pkg_cls (spack.package_base.PackageBase): the package class
                 that required the validation, if available
 
-        Raises: Exception
+        Raises:
+            Exception
         """
         # If the value is exclusive there must be at most one
         if not self.multi and len(variant_values) != 1: