raphael-group · vineetbansal · Dec 3, 2020 · Dec 3, 2020 · Dec 3, 2020 · Dec 4, 2020
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -2,12 +2,12 @@ name: CI
 
 on:
   push:
-    branches: [ master, develop, py3, ci ]
+    branches: [ master, develop, py3, ci, docs ]
   pull_request:
-    branches: [ master, develop, py3, ci ]
+    branches: [ master, develop, py3, ci, docs ]
 
 jobs:
-  build:
+  run_tests:
 
     runs-on: ubuntu-latest
     strategy:
@@ -71,3 +71,41 @@ jobs:
           tox
         env:
           PLATFORM: ${{ matrix.python }}
+
+  build_docs:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: [2.7]
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          lfs: true 
+
+      - name: Upgrade setuptools
+        run: |
+          pip3 install wheel --upgrade
+          pip3 install setuptools --upgrade
+
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install package
+        run: |
+          pip install .
+          pip install numpydoc sphinx sphinx-rtd-theme recommonmark sphinx-markdown-tables
+
+      - name: Build docs
+        run: |
+          cd docs && sphinx-apidoc -f -o ./source/src ../src/chisel -H Modules && make html && touch build/html/.nojekyll
+
+      - name: Update gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: "docs/buildDocs.sh"
+        shell: bash
+
diff --git a/README.md b/README.md
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = chisel 
+SOURCEDIR     = source
+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
+
+# 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)
diff --git a/docs/buildDocs.sh b/docs/buildDocs.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Adapted from:
+# https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/
+
+set -x
+pwd
+ls -lah
+export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
+
+#######################
+# Update GitHub Pages #
+#######################
+
+git config --global user.name "${GITHUB_ACTOR}"
+git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+docroot=`mktemp -d`
+rsync -av "docs/build/html/" "${docroot}/"
+
+pushd "${docroot}"
+
+# don't bother maintaining history; just generate fresh
+git init
+git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+git checkout -b gh-pages
+
+# Add README
+cat > README.md <<EOF
+# CHISEL 
+
+CHISEL documentation is available at [http://compbio.cs.brown.edu/chisel/](http://compbio.cs.brown.edu/chisel/)
+
+EOF
+
+# copy the resulting html pages built from sphinx above to our new git repo
+git add .
+
+# commit all the new files
+msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}"
+git commit -am "${msg}"
+
+# overwrite the contents of the gh-pages branch on our github.com repo
+git push deploy gh-pages --force
+
+popd # return to main repo sandbox root
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=BSS
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/docs/source/README.md b/docs/source/README.md
diff --git a/doc/chisel-calling.md → docs/source/chisel-calling.md b/doc/chisel-calling.md → docs/source/chisel-calling.md
diff --git a/docs/source/chisel-cartoon.png b/docs/source/chisel-cartoon.png
diff --git a/doc/chisel-cloning.md → docs/source/chisel-cloning.md b/doc/chisel-cloning.md → docs/source/chisel-cloning.md
diff --git a/doc/chisel-plotting.md → docs/source/chisel-plotting.md b/doc/chisel-plotting.md → docs/source/chisel-plotting.md
diff --git a/doc/chisel-pseudonormal.md → docs/source/chisel-pseudonormal.md b/doc/chisel-pseudonormal.md → docs/source/chisel-pseudonormal.md
diff --git a/doc/chisel.md → docs/source/chisel.md b/doc/chisel.md → docs/source/chisel.md
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# BSS documentation build configuration file, created by
+# sphinx-quickstart on Tue May  1 10:26:43 2018.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# 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
+import sphinx_rtd_theme
+sys.path.insert(0, os.path.abspath('../src'))
+import chisel 
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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.mathjax', 'numpydoc', 'recommonmark', 'sphinx_markdown_tables']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md', '.sh']
+# source_suffix = '.rst'
+
+# Extra file to copy over to the build directory
+html_extra_path = ['../../install_full.sh']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'CHISEL'
+copyright = '2021, Princeton University'
+author = 'Simone Zaccaria'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = chisel.__version__
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- 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'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'chisel'
+
+autoclass_content = 'both'
diff --git a/docs/source/demos b/docs/source/demos
@@ -0,0 +1 @@
+../../demos/
diff --git a/docs/source/guides b/docs/source/guides
@@ -0,0 +1 @@
+../../guides/
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,21 @@
+CHISEL
+=======
+
+CHISEL is an algorithm to infer allele- and haplotype-specific copy numbers in individual cells from low-coverage single-cell DNA sequencing data.
+
+.. toctree::
+
+    README
+
+.. toctree::
+   :titlesonly:
+
+   modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/man b/docs/source/man
@@ -0,0 +1 @@
+../../man/
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+Modules
+=======
+
+.. toctree::
+   :maxdepth: 4
+
+   src/chisel
diff --git a/guides/clones.md b/guides/clones.md
@@ -12,6 +12,6 @@ Therefore, when the user observes a outlying high number of noisy cells or too f
 
 Given the inferred clones with the previous parameters, there is one additional parameter that can be used to adjust the classification of noisy cells: `-r`, which controls the refinement of the identified clones and allows the user to include more "noisy" cells into the identified clones. Specifically, every cell that has a fraction of the genome with different haplotype-specific copy numbers lower than then value of `r` will be included into the clones. Therefore, the user can user increasingly higher values to force the inclusion of more noisy cells into the inferred clones, for example `-r 0.2`, `-r 0.3`, `-r 0.4`, etc. Note that `-r 1` will force every cell to be assigned to a clone.
 
-These tasks can be performed very efficiently and easily by using the [CHISEL command `chisel-cloning.py`](../doc/chisel-cloning.md), which allows the user to only re-execute the inference of clones and the generation of plots very efficiently from the already inferred haploty-specific copy numbers.
+These tasks can be performed very efficiently and easily by using the [CHISEL command `chisel-cloning.py`](../chisel-cloning.html), which allows the user to only re-execute the inference of clones and the generation of plots very efficiently from the already inferred haploty-specific copy numbers.
 As such, using this command, the user can attempt to use different combinations of the parameters, varying the maximum difference `f` (e.g. `-f 0.1`, `-f 0.12`, `-f 0.15`, ...) and the minimum number `-s` of cells to select the clones (either increasing like `-s 20`, `-s 30`, ... or decreasing like `-s 3`, `-s 2`, according to the total number of cells).
 More details on adjusting and selecting reasonable values of these parameters are available in the [CHISEL's manuscript](https://doi.org/10.1101/837195).
diff --git a/guides/clustering.md b/guides/clustering.md
@@ -3,8 +3,8 @@
 CHISEL globally clusters the estimated RDRs and BAFs by using a k-means algorithm and model-selection criterion based on the elbow method to select the best number of clusters (further details are reported in the [CHISEL's manuscript](https://doi.org/10.1101/837195)).
 In order to do this, CHISEL fixes the maximum number of clusters (default value is 100).
 However, the value can be too high when analyzing very noisy datasets since the high levels of noise in the data can be misinterpreted and may lead to overfitting.
-Therefore, the user can assess the levels of variance and noise by using the [BAF and RDR plots](../doc/chisel-plotting.md): in particular, high levels of noise can be immediately noted when a clear clustering structure is missing from such plots. 
+Therefore, the user can assess the levels of variance and noise by using the [BAF and RDR plots](../chisel-plotting.html): in particular, high levels of noise can be immediately noted when a clear clustering structure is missing from such plots. 
 As such, when analyzing datasets with very high levels of variance, the user can lower the maximum number of clusters to avoid overfitting.
 Another possible signal that may indicate overiffing is for example the inference of many outlying and noisy CNAs, i.e. observing many cells with isolated and small CNAs.
-For such QC purposes, the user can use the CHISEL [command `chisel-calling.py`](../doc/chisel-calling.md) to vary the maximum number of clusters with the argument `-K` to re-run the CHISEL inference without the need of re-estimating RDRs and BAFs (which generally is the most time-consuming step).
+For such QC purposes, the user can use the CHISEL [command `chisel-calling.py`](../chisel-calling.html) to vary the maximum number of clusters with the argument `-K` to re-run the CHISEL inference without the need of re-estimating RDRs and BAFs (which generally is the most time-consuming step).
 The user can thus quantify the presence of noisy CNAs when varying the value of this parameter, for example `-K 80`, `-K 60`, `-K 40`...
diff --git a/guides/ploidy.md b/guides/ploidy.md
@@ -5,8 +5,8 @@ In the case of particularly noisy cells or datasets with a particularly low sequ
 A sign which generally indicates potential issues in the inference of cell ploidies is the observation of a substatial number of cells with different ploidies (and thus with completely different copy numbers).
 However, CHISEL provides a parameter to adjust the sensitivity of the model-selection criterion for dealing with these cases.
 
-For QC purposes, the reccommendation is to analyze the allele-specific copy numbers inferred by CHISEL, for example using the corresponding [plots](../doc/chisel-plotting.md).
+For QC purposes, the reccommendation is to analyze the allele-specific copy numbers inferred by CHISEL, for example using the corresponding [plots](../chisel-plotting.html).
 If a substantial number of cells with different ploidies has been inferred, the reccommendation is to analyze how the results change by re-running the inference of copy numbers varying the sensitivity of the model-selection criterion.
-Specifically, the CHISEL [command `chisel-calling.py`](../doc/chisel-calling.md) can be used to do this very efficiently by varying the sensitivity with the argument `-A` to re-run the CHISEL inference without the need of re-estimating RDRs and BAFs (which generally is the most time-consuming step).
+Specifically, the CHISEL [command `chisel-calling.py`](../chisel-calling.html) can be used to do this very efficiently by varying the sensitivity with the argument `-A` to re-run the CHISEL inference without the need of re-estimating RDRs and BAFs (which generally is the most time-consuming step).
 The use can thus analyse the inferred tumor ploidies by increase the sensitivity with values of `-A 2`, `-A 3`, `-A 4`...
 The inference of different ploidies is well supported by the data if the results do not substantially change when increasing the sensitivity, otherwise the results obtained with higher sensitivity are more likely.