Skip to content

Commit 32983c2

Browse files
vineetbansalvineetbansal
committed
sphinx docs
1 parent 803fcf1 commit 32983c2

21 files changed

+527
-7
lines changed

‎.github/workflows/main.yml

+38-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ on:
77
branches: [ master, develop, py3, ci ]
88

99
jobs:
10-
build:
10+
run_tests:
1111

1212
runs-on: ubuntu-latest
1313
strategy:
@@ -71,3 +71,40 @@ jobs:
7171
tox
7272
env:
7373
PLATFORM: ${{ matrix.python }}
74+
75+
build_docs:
76+
77+
runs-on: ubuntu-latest
78+
strategy:
79+
matrix:
80+
python: [2.7]
81+
82+
steps:
83+
- uses: actions/checkout@v2
84+
with:
85+
lfs: true
86+
87+
- name: Upgrade setuptools
88+
run: |
89+
pip3 install wheel --upgrade
90+
pip3 install setuptools --upgrade
91+
92+
- name: Setup Python
93+
uses: actions/setup-python@v2
94+
with:
95+
python-version: ${{ matrix.python }}
96+
97+
- name: Install package
98+
run: |
99+
pip install .[dev]
100+
101+
- name: Build docs
102+
run: |
103+
cd docs && sphinx-apidoc -f -o ./source/src ../src/chisel -H Modules && make html && touch build/html/.nojekyll
104+
105+
- name: Update gh-pages
106+
env:
107+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
108+
run: "docs/buildDocs.sh"
109+
shell: bash
110+

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = chisel
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/buildDocs.sh

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
#!/bin/bash
2+
3+
# Adapted from:
4+
# https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/
5+
6+
set -x
7+
pwd
8+
ls -lah
9+
export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
10+
11+
#######################
12+
# Update GitHub Pages #
13+
#######################
14+
15+
git config --global user.name "${GITHUB_ACTOR}"
16+
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
17+
18+
docroot=`mktemp -d`
19+
rsync -av "docs/build/html/" "${docroot}/"
20+
21+
pushd "${docroot}"
22+
23+
# don't bother maintaining history; just generate fresh
24+
git init
25+
git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
26+
git checkout -b gh-pages
27+
28+
# Add README
29+
cat > README.md <<EOF
30+
# CHISEL
31+
32+
CHISEL documentation is available at [http://compbio.cs.brown.edu/chisel/](http://compbio.cs.brown.edu/chisel/)
33+
34+
EOF
35+
36+
# copy the resulting html pages built from sphinx above to our new git repo
37+
git add .
38+
39+
# commit all the new files
40+
msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}"
41+
git commit -am "${msg}"
42+
43+
# overwrite the contents of the gh-pages branch on our github.com repo
44+
git push deploy gh-pages --force
45+
46+
popd # return to main repo sandbox root

‎docs/make.bat

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=python -msphinx
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
set SPHINXPROJ=BSS
13+
14+
if "%1" == "" goto help
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
20+
echo.then set the SPHINXBUILD environment variable to point to the full
21+
echo.path of the 'sphinx-build' executable. Alternatively you may add the
22+
echo.Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

‎docs/source/README.md

+252
Large diffs are not rendered by default.

‎doc/chisel-calling.md renamed to ‎docs/source/chisel-calling.md

File renamed without changes.

‎docs/source/chisel-cartoon.png

2.1 MB
Loading

‎doc/chisel-cloning.md renamed to ‎docs/source/chisel-cloning.md

File renamed without changes.

‎doc/chisel-plotting.md renamed to ‎docs/source/chisel-plotting.md

File renamed without changes.

‎doc/chisel-pseudonormal.md renamed to ‎docs/source/chisel-pseudonormal.md

File renamed without changes.

‎doc/chisel.md renamed to ‎docs/source/chisel.md

File renamed without changes.

‎docs/source/conf.py

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
#!/usr/bin/env python3
2+
# -*- coding: utf-8 -*-
3+
#
4+
# BSS documentation build configuration file, created by
5+
# sphinx-quickstart on Tue May 1 10:26:43 2018.
6+
#
7+
# This file is execfile()d with the current directory set to its
8+
# containing dir.
9+
#
10+
# Note that not all possible configuration values are present in this
11+
# autogenerated file.
12+
#
13+
# All configuration values have a default; values that are commented out
14+
# serve to show the default.
15+
16+
# If extensions (or modules to document with autodoc) are in another directory,
17+
# add these directories to sys.path here. If the directory is relative to the
18+
# documentation root, use os.path.abspath to make it absolute, like shown here.
19+
#
20+
import os
21+
import sys
22+
import sphinx_rtd_theme
23+
sys.path.insert(0, os.path.abspath('../src'))
24+
import chisel
25+
26+
# -- General configuration ------------------------------------------------
27+
28+
# If your documentation needs a minimal Sphinx version, state it here.
29+
#
30+
# needs_sphinx = '1.0'
31+
32+
# Add any Sphinx extension module names here, as strings. They can be
33+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
34+
# ones.
35+
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'numpydoc', 'recommonmark', 'sphinx_markdown_tables']
36+
37+
# Add any paths that contain templates here, relative to this directory.
38+
templates_path = ['_templates']
39+
40+
# The suffix(es) of source filenames.
41+
# You can specify multiple suffix as a list of string:
42+
#
43+
# source_suffix = ['.rst', '.md', '.sh']
44+
# source_suffix = '.rst'
45+
46+
# Extra file to copy over to the build directory
47+
html_extra_path = ['../../install_full.sh']
48+
49+
# The master toctree document.
50+
master_doc = 'index'
51+
52+
# General information about the project.
53+
project = 'CHISEL'
54+
copyright = '2021, Princeton University'
55+
author = 'Simone Zaccaria'
56+
57+
# The version info for the project you're documenting, acts as replacement for
58+
# |version| and |release|, also used in various other places throughout the
59+
# built documents.
60+
#
61+
# The short X.Y version.
62+
version = chisel.__version__
63+
# The full version, including alpha/beta/rc tags.
64+
release = version
65+
66+
# The language for content autogenerated by Sphinx. Refer to documentation
67+
# for a list of supported languages.
68+
#
69+
# This is also used if you do content translation via gettext catalogs.
70+
# Usually you set "language" from the command line for these cases.
71+
language = None
72+
73+
# List of patterns, relative to source directory, that match files and
74+
# directories to ignore when looking for source files.
75+
# This patterns also effect to html_static_path and html_extra_path
76+
exclude_patterns = []
77+
78+
# The name of the Pygments (syntax highlighting) style to use.
79+
pygments_style = 'sphinx'
80+
81+
# If true, `todo` and `todoList` produce output, else they produce nothing.
82+
todo_include_todos = False
83+
84+
85+
# -- Options for HTML output ----------------------------------------------
86+
87+
# The theme to use for HTML and HTML Help pages. See the documentation for
88+
# a list of builtin themes.
89+
#
90+
html_theme = 'sphinx_rtd_theme'
91+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
92+
93+
# -- Options for HTMLHelp output ------------------------------------------
94+
95+
# Output file base name for HTML help builder.
96+
htmlhelp_basename = 'chisel'
97+
98+
autoclass_content = 'both'

‎docs/source/demos

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../demos/

‎docs/source/guides

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../guides/

‎docs/source/index.rst

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
CHISEL
2+
=======
3+
4+
CHISEL is an algorithm to infer allele- and haplotype-specific copy numbers in individual cells from low-coverage single-cell DNA sequencing data.
5+
6+
.. toctree::
7+
8+
README
9+
10+
.. toctree::
11+
:titlesonly:
12+
13+
modules
14+
15+
16+
Indices and tables
17+
==================
18+
19+
* :ref:`genindex`
20+
* :ref:`modindex`
21+
* :ref:`search`

‎docs/source/man

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../man/

‎docs/source/modules.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Modules
2+
=======
3+
4+
.. toctree::
5+
:maxdepth: 4
6+
7+
src/chisel

‎guides/clones.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,6 @@ This identification is controlled by two parameters:
99
The values of these two parameters have been calibrated for the expected number of cells and sequencing coverage of 10X Genomics datasets.
1010
However, when analyzing datasets with different number of cells, different sequencing coverage, or particularly noisy datasets, the default values of these parameters may not be appropriate.
1111
Therefore, when the user observes a outlying high number of noisy cells or too few inferred clones (even 0), it is important to vary these values to explore different solutions.
12-
This can be done 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.
12+
This can be done 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.
1313
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).
1414
More details on adjusting and selecting reasonable values of these parameters are available in the [CHISEL's manuscript](https://doi.org/10.1101/837195).

‎guides/clustering.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
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)).
44
In order to do this, CHISEL fixes the maximum number of clusters (default value is 100).
55
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.
6-
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.
6+
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.
77
As such, when analyzing datasets with very high levels of variance, the user can lower the maximum number of clusters to avoid overfitting.
88
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.
9-
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).
9+
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).
1010
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`...

‎guides/ploidy.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ In the case of particularly noisy cells or datasets with a particularly low sequ
55
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).
66
However, CHISEL provides a parameter to adjust the sensitivity of the model-selection criterion for dealing with these cases.
77

8-
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).
8+
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).
99
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.
10-
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).
10+
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).
1111
The use can thus analyse the inferred tumor ploidies by increase the sensitivity with values of `-A 2`, `-A 3`, `-A 4`...
1212
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.

‎setup.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
'seaborn>=0.7.1'
2222
],
2323
extras_require={
24-
'dev': ['pytest', 'mock']
24+
'dev': ['pytest', 'mock', 'numpydoc', 'sphinx', 'sphinx-rtd-theme', 'recommonmark', 'sphinx-markdown-tables']
2525
},
2626
license='BSD',
2727
platforms=["Linux", "MacOs", "Windows"],

0 commit comments

Comments
 (0)