docs: Add docstrings for src/pyhf/infer (#698)

* Add pydocstyle compliant docstrings to the infer module

Author: lukasheinrich

src/pyhf/infer/__init__.py

@@ -1,3 +1,5 @@
+"""Inference for Statistical Models."""
+
 from .test_statistics import qmu
 from .utils import (
     generate_asimov_data,
@@ -11,7 +13,7 @@ def hypotest(
     poi_test, data, pdf, init_pars=None, par_bounds=None, qtilde=False, **kwargs
 ):
     r"""
-    Computes :math:`p`-values and test statistics for a single value of the parameter of interest
+    Compute :math:`p`-values and test statistics for a single value of the parameter of interest.
 
     Args:
         poi_test (Number or Tensor): The value of the parameter of interest (POI)
@@ -75,7 +77,6 @@ def hypotest(
             - :math:`\left[q_{\mu}, q_{\mu,A}\right]`: The test statistics for the observed and Asimov datasets respectively. Only returned when ``return_test_statistics`` is ``True``.
 
     """
-
     init_pars = init_pars or pdf.config.suggested_init()
     par_bounds = par_bounds or pdf.config.suggested_bounds()
     tensorlib, _ = get_backend()

src/pyhf/infer/utils.py

@@ -1,3 +1,4 @@
+"""Utility Functions for model inference."""
 from .. import get_backend
 
 
@@ -15,6 +16,8 @@ def generate_asimov_data(asimov_mu, data, pdf, init_pars, par_bounds):
 
 def pvals_from_teststat(sqrtqmu_v, sqrtqmuA_v, qtilde=False):
     r"""
+    Compute p-values from test-statistic values.
+
     The :math:`p`-values for signal strength :math:`\mu` and Asimov strength :math:`\mu'` as defined in Equations (59) and (57) of :xref:`arXiv:1007.1727`
 
     .. math::
@@ -36,6 +39,7 @@ def pvals_from_teststat(sqrtqmu_v, sqrtqmuA_v, qtilde=False):
 
     Returns:
         Tuple of Floats: The :math:`p`-values for the signal + background, background only, and signal only hypotheses respectivley
+
     """
     tensorlib, _ = get_backend()
     if not qtilde:  # qmu
@@ -66,16 +70,16 @@ def _false_case():
 
 def pvals_from_teststat_expected(sqrtqmuA_v, nsigma=0):
     r"""
-    Computes the expected :math:`p`-values CLsb, CLb and CLs for data corresponding to a given percentile of the alternate hypothesis.
+    Compute the expected :math:`p`-values CLsb, CLb and CLs for data corresponding to a given percentile of the alternate hypothesis.
 
     Args:
         sqrtqmuA_v (Number or Tensor): The root of the calculated test statistic given the Asimov data, :math:`\sqrt{q_{\mu,A}}`
         nsigma (Number or Tensor): The number of standard deviations of variations of the signal strength from the background only hypothesis :math:`\left(\mu=0\right)`
 
     Returns:
         Tuple of Floats: The :math:`p`-values for the signal + background, background only, and signal only hypotheses respectivley
-    """
 
+    """
     # NOTE:
     # To compute the expected p-value, one would need to first compute a hypothetical
     # observed test-statistic for a dataset whose best-fit value is mu^ = mu'-n*sigma: