Add missing API docs to Sphinx. Fixes sgkit-dev#212 (sgkit-dev#214)

Author: tomwhite

docs/api.rst

@@ -6,11 +6,32 @@ API reference
 
 This page provides an auto-generated summary of sgkits's API.
 
-Top-level functions
-===================
+Creating a dataset
+==================
 
 .. autosummary::
    :toctree: generated/
 
    create_genotype_call_dataset
+   create_genotype_dosage_dataset
+   read_vcfzarr
+
+Methods
+=======
+
+.. autosummary::
+   :toctree: generated/
+
+   count_call_alleles
+   count_variant_alleles
    gwas_linear_regression
+   hardy_weinberg_test
+   regenie
+
+Utilities
+=========
+
+.. autosummary::
+   :toctree: generated/
+
+   display_genotypes

sgkit/api.py

@@ -93,7 +93,7 @@ def create_genotype_dosage_dataset(
     call_genotype_probability: Any,
     variant_id: Any = None,
 ) -> xr.Dataset:
-    """Create a dataset of genotype calls.
+    """Create a dataset of genotype dosages.
 
     Parameters
     ----------

sgkit/stats/hwe.py

@@ -145,7 +145,7 @@ def hardy_weinberg_test(
     Dataset
         Dataset containing (N = num variants):
         variant_hwe_p_value : (N,) ArrayLike
-            P values from HWE test for each variant as float in [0, 1].
+        P values from HWE test for each variant as float in [0, 1].
 
     References
     ----------
@@ -156,8 +156,9 @@ def hardy_weinberg_test(
     Raises
     ------
     NotImplementedError
-        * If ploidy of provided dataset != 2
-        * If maximum number of alleles in provided dataset != 2
+        If ploidy of provided dataset != 2
+    NotImplementedError
+        If maximum number of alleles in provided dataset != 2
     """
     if ds.dims["ploidy"] != 2:
         raise NotImplementedError("HWE test only implemented for diploid genotypes")

sgkit/stats/regenie.py

@@ -736,7 +736,7 @@ def regenie(
 ) -> Dataset:
     """Regenie trait transformation.
 
-    [REGENIE](https://github.com/rgcgithub/regenie) is a whole-genome
+    `REGENIE <https://github.com/rgcgithub/regenie>`_ is a whole-genome
     regression technique that produces trait estimates for association
     tests. These estimates are subtracted from trait values and
     sampling statistics (p-values, standard errors, etc.) are evaluated
@@ -790,14 +790,20 @@ def regenie(
     Dataset
         A dataset containing the following variables:
         - `base_prediction` (blocks, alphas, samples, outcomes): Stage 1
-            predictions from ridge regression reduction .
+        predictions from ridge regression reduction .
         - `meta_prediction` (samples, outcomes): Stage 2 predictions from
-            the best meta estimator trained on the out-of-sample Stage 1
-            predictions.
+        the best meta estimator trained on the out-of-sample Stage 1
+        predictions.
         - `loco_prediction` (contigs, samples, outcomes): LOCO predictions
-            resulting from Stage 2 predictions ignoring effects for variant
-            blocks on held out contigs. This will be absent if the
-            data provided does not contain at least 2 contigs.
+        resulting from Stage 2 predictions ignoring effects for variant
+        blocks on held out contigs. This will be absent if the
+        data provided does not contain at least 2 contigs.
+
+    Raises
+    ------
+    ValueError
+        If dosage, covariates, and trait arrays do not have the same number
+        of samples.
 
     Examples
     --------
@@ -824,15 +830,10 @@ def regenie(
     References
     ----------
     [1] - Mbatchou, J., L. Barnard, J. Backman, and A. Marcketta. 2020.
-        “Computationally Efficient Whole Genome Regression for Quantitative and Binary
-        Traits.” bioRxiv. https://www.biorxiv.org/content/10.1101/2020.06.19.162354v2.abstract.
-    [2] - https://glow.readthedocs.io/en/latest/tertiary/whole-genome-regression.html
+    “Computationally Efficient Whole Genome Regression for Quantitative and Binary
+    Traits.” bioRxiv. https://www.biorxiv.org/content/10.1101/2020.06.19.162354v2.abstract.
 
-    Raises
-    ------
-    ValueError
-        If dosage, covariates, and trait arrays do not have the same number
-        of samples.
+    [2] - https://glow.readthedocs.io/en/latest/tertiary/whole-genome-regression.html
     """
     if isinstance(covariates, str):
         covariates = [covariates]