Add usage and design documentation (#278)

* Add usage and design documentation #87 * Update docs/index.rst Co-authored-by: Alistair Miles <[email protected]> * Suggested changes Co-authored-by: Alistair Miles <[email protected]> * Force push gh-pages branch in gh action * Suggested changes * Fix typo Co-authored-by: Alistair Miles <[email protected]>
sgkit-dev · Sep 30, 2020 · d588980 · d588980
1 parent cc7aa7f
commit d588980
Show file tree

Hide file tree

Showing 14 changed files with 532 additions and 45 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -39,4 +39,5 @@ jobs:
       with:
         branch: gh-pages
         directory: gh-pages
+        force: true
         github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+savefig/
diff --git a/docs/_static/data-structures-xarray.jpg b/docs/_static/data-structures-xarray.jpg
diff --git a/docs/api.rst b/docs/api.rst
@@ -30,6 +30,8 @@ Creating a dataset
    create_genotype_call_dataset
    create_genotype_dosage_dataset
 
+.. _api_methods:
+
 Methods
 =======
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -47,6 +47,8 @@
     "sphinx.ext.githubpages",
     "sphinx.ext.intersphinx",
     "scanpydoc",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "IPython.sphinxext.ipython_directive",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
 ]
 

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -271,3 +271,43 @@ We use `mergify <https://mergify.io/>`_ to automate PR flow. A project
 to automatically merge a PR by labeling it with ``auto-merge``, and when the PR gets:
 at least one +1 (from [committers](https://github.com/orgs/pystatgen/teams/committers))
 and a clean build it will get merged automatically.
+
+Design discussions
+------------------
+
+The information on these topics may be useful for developers in understanding the
+history behind the design choices that have been made within the project so far.
+
+Dataset sublcassing
+~~~~~~~~~~~~~~~~~~~
+
+Debates on whether or not we should use Xarray objects directly or
+put them behind a layer of encapsulation:
+
+- https://github.com/pystatgen/sgkit/pull/16#issuecomment-657725092
+- https://github.com/pystatgen/sgkit/pull/78#issuecomment-669878845
+
+Dataset API typing
+~~~~~~~~~~~~~~~~~~
+
+Discussions around bringing stricter array type enforcement into the API:
+
+- https://github.com/pystatgen/sgkit/issues/43
+- https://github.com/pystatgen/sgkit/pull/124
+- https://github.com/pystatgen/sgkit/pull/276
+
+
+Delayed invariant checks
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Discussions on how to run sanity checks on arrays efficiently and why those checks would be
+useful if they were possible (they are not possible currently w/ Dask):
+
+- https://github.com/pystatgen/sgkit/issues/61
+- https://github.com/dask/dask/issues/97
+
+Mixed ploidy
+~~~~~~~~~~~~
+
+Proposal for handling mixed ploidy: https://github.com/pystatgen/sgkit/issues/243
+