Fixing conflicts

Author: eric-czech

.github/workflows/build.yml

@@ -19,6 +19,10 @@ jobs:
         pip install -r requirements.txt -r requirements-dev.txt
     - name: Run pre-commit
       uses: pre-commit/[email protected]
+    - name: Check for Sphinx doc warnings
+      run: |
+        cd docs
+        make html SPHINXOPTS="-W --keep-going"
     - name: Test with pytest and coverage
       run: |
         pytest -v --cov=sgkit --cov-report=term-missing

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Publish documentation
+
+on:
+  push:
+    branches:    
+      - master
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.8'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt -r requirements-dev.txt
+    - name: Build Sphinx documentation
+      run: |
+        cd docs
+        make html SPHINXOPTS="-W --keep-going"
+    - name: Commit documentation changes to gh-pages branch
+      run: |
+        git clone https://github.com/pystatgen/sgkit.git --branch gh-pages --single-branch gh-pages
+        cp -r docs/_build/html/* gh-pages/
+        cd gh-pages
+        git config --local user.email "[email protected]"
+        git config --local user.name "GitHub Action"
+        git add .
+        git commit -m "Update documentation" -a || true # Ignore error if no changes present
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        branch: gh-pages
+        directory: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -132,4 +132,6 @@ dmypy.json
 .vscode
 .idea
 .DS_Store
-._.DS_Store
+
+# sgkit
+docs/generated

README.md

@@ -18,6 +18,13 @@ To check code coverage and get a coverage report, run
 pytest --cov=sgkit --cov-report term-missing
 ```
 
+To check that the documentation builds without warnings, run
+
+```bash
+cd docs
+make clean html SPHINXOPTS="-W --keep-going"
+```
+
 ### Code standards
 
 Use [pre-commit](https://pre-commit.com/) to check or enforce the coding standards. Install the git hook using:

docs/Makefile

@@ -0,0 +1,25 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf generated/*
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,16 @@
+.. currentmodule:: sgkit
+
+#############
+API reference
+#############
+
+This page provides an auto-generated summary of sgkits's API.
+
+Top-level functions
+===================
+
+.. autosummary::
+   :toctree: generated/
+
+   create_genotype_call_dataset
+   gwas_linear_regression

docs/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+print("python exec:", sys.executable)
+print("sys.path:", sys.path)
+
+import sgkit  # noqa: F401 isort:skip
+
+# -- Project information -----------------------------------------------------
+
+project = "sgkit"
+copyright = "2020, sgkit developers"
+author = "sgkit developers"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+autosummary_generate = True
+
+intersphinx_mapping = {
+    "xarray": ("http://xarray.pydata.org/en/stable/", None),
+    "zarr": ("https://zarr.readthedocs.io/en/stable", None),
+}
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,15 @@
+sgkit: Statistical genetics toolkit in Python
+=============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

requirements-dev.txt

@@ -6,3 +6,5 @@ pytest-datadir
 hypothesis
 statsmodels
 zarr
+sphinx
+sphinx_rtd_theme

setup.cfg

@@ -39,6 +39,7 @@ fail_under = 100
 
 [tool:pytest]
 addopts = --doctest-modules --ignore=validation
+norecursedirs = .eggs docs
 
 [flake8]
 ignore =

sgkit/api.py

@@ -49,7 +49,7 @@ def create_genotype_call_dataset(
 
     Returns
     -------
-    xr.Dataset
+    :class:`xarray.Dataset`
         The dataset of genotype calls.
 
     """

sgkit/stats/association.py

@@ -160,6 +160,17 @@ def gwas_linear_regression(
     along the sample (row) dimension but not the column dimension (i.e.
     they must be tall and skinny).
 
+    Returns
+    -------
+    :class:`xarray.Dataset`
+        Dataset containing (N = num variants, O = num traits):
+            beta : (N, O) array-like
+                Beta values associated with each variant and trait
+            t_value : (N, O) array-like
+                T statistics for each beta
+            p_value : (N, O) array-like
+                P values as float in [0, 1]
+
     Warnings
     --------
     Regression statistics from this implementation are only valid when an
@@ -181,16 +192,7 @@ def gwas_linear_regression(
         Bayesian Mixed-Model Analysis Increases Association Power in Large Cohorts.”
         Nature Genetics 47 (3): 284–90.
 
-    Returns
-    -------
-    Dataset
-        Dataset containing (N = num variants, O = num traits):
-        beta : (N, O) array-like
-            Beta values associated with each variant and trait
-        t_value : (N, O) array-like
-            T statistics for each beta
-        p_value : (N, O) array-like
-            P values as float in [0, 1]
+
     """
     if isinstance(covariates, str):
         covariates = [covariates]