Convert docs to jupyterbook

Author: Ben Jeffery

.circleci/config.yml

@@ -93,14 +93,6 @@ jobs:
           name: Build the distribution tarball.
           command: python setup.py sdist
 
-      - run:
-          name: Test the docs will build on RTD minimal environment.
-          command: |
-               python -m venv docs-venv
-               source docs-venv/bin/activate
-               pip install -r requirements/readthedocs.txt
-               make -C docs
-
       - run:
           name: Install from the distribution tarball
           command: |

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags:
+      - '*'
+
+env:
+  COMMIT_EMAIL: [email protected]
+  MAKE_TARGET: all
+  OWNER: tskit-dev
+  REPO: tsinfer
+
+jobs:
+  build-deploy-docs:
+    name: Docs
+    runs-on: ubuntu-18.04
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+
+      - uses: actions/checkout@v2
+        # As we are using pull-request-target which uses the workflow from the base
+        # of the PR, we need to be specific
+        with:
+            ref: ${{ github.event.pull_request.head.ref }}
+            repository: ${{ github.event.pull_request.head.repo.full_name }}
+            submodules: true
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+
+      - uses: actions/cache@v2
+        id: cache
+        with:
+          path: venv
+          key: docs-venv-v1-${{ hashFiles('requirements/CI-docs/requirements.txt') }}
+
+      - name: Build virtualenv
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: python -m venv venv
+
+      - name: Install deps
+        run: venv/bin/activate && pip install -r requirements/CI-docs/requirements.txt
+
+      - name: Build C module
+        if: env.MAKE_TARGET
+        run: venv/bin/activate && make $MAKE_TARGET
+
+      - name: Build Docs
+        run: venv/bin/activate && cd docs && make dist
+
+      - name: Trigger docs site rebuild
+        if: github.ref == 'refs/heads/main'
+        run: |
+          curl -X POST https://api.github.com/repos/tskit-dev/tskit-site/dispatches \
+                    -H 'Accept: application/vnd.github.everest-preview+json' \
+                    -u AdminBot-tskit:${{ secrets.ADMINBOT_TOKEN }} \
+                    --data '{"event_type":"build-docs"}'

CHANGELOG.rst renamed to CHANGELOG.md

@@ -1,90 +1,82 @@
-********************
-[0.2.4] - 2022-06-xx
-********************
+# Changelog
+
+## [0.2.4] - 2022-06-xx
 
 **Features**
 
 - matching routines warn if no inference sites
-  (:pr:`685`, :issue:`683` :user:`hyanwong`)
+  ({pr}`685`, {issue}`683` {user}`hyanwong`)
 
 **Fixes**
 
-- sample_data.subset() now accepts a sequence_length  (:pr:`681`, :user:`hyanwong`)
+- sample_data.subset() now accepts a sequence_length  ({pr}`681`, {user}`hyanwong`)
 
 **Breaking changes**:
 
 - Inference now sets time_units on both ancestor and final tree sequences to
   tskit.TIME_UNITS_UNCALIBRATED, stopping accidental use of branch length
-  calculations on the ts. (:pr:`680`, :user:`hyanwong`)
+  calculations on the ts. ({pr}`680`, {user}`hyanwong`)
 
-********************
-[0.2.3] - 2022-04-08
-********************
+## [0.2.3] - 2022-04-08
 
 **Features**
 
-- Added ``ancestor(id)`` to ``AncestorData`` class.
-  (:pr:`570`, :issue:`569`, :user:`hyanwong`)
+- Added `ancestor(id)` to `AncestorData` class.
+  ({pr}`570`, {issue}`569`, {user}`hyanwong`)
 
 **Fixes**
 
-- Mark zarr 2.11.0, 2.11.1 and 2.11.2 as incompatible due to ``zarr-python``
+- Mark zarr 2.11.0, 2.11.1 and 2.11.2 as incompatible due to `zarr-python`
   bugs #965 and #967.
-  (:issue:`643`, :pr:`657`, :user:`benjeffery`)
+  ({issue}`643`, {pr}`657`, {user}`benjeffery`)
 
-********************
-[0.2.2] - 2022-02-23
-********************
+## [0.2.2] - 2022-02-23
 
 **Bugfixes**:
 
 - Mutations at non-inference sites are now guaranteed to be fully parsimonious.
   Previous versions required a mutation above the root when the input ancestral state
   disagreed with the ancestral state produced by the parsimony algorithm. Now fixed by
-  using the new map_mutations code from tskit 0.3.7 (:pr:`557`, :user:`hyanwong`)
+  using the new map_mutations code from tskit 0.3.7 ({pr}`557`, {user}`hyanwong`)
 
 **New Features**:
 
 **Breaking changes**:
 
 - Oldest nodes in a standard inferred tree sequence are no longer set to frequencies ~2
   and ~3 (i.e. 2 or 3 times as old as all the other nodes), but are spaced above the
-  others by the mean time between unique ancestor ages (:pr:`485`, :user:`hyanwong`)
+  others by the mean time between unique ancestor ages ({pr}`485`, {user}`hyanwong`)
 
-- The ``tsinfer.SampleData.from_tree_sequence()`` function now defaults to setting
-  ``use_sites_time`` and ``use_individuals_time`` to ``False`` rather than ``True``
-  (:pr:`599`, :user:`hyanwong`)
+- The `tsinfer.SampleData.from_tree_sequence()` function now defaults to setting
+  `use_sites_time` and `use_individuals_time` to `False` rather than `True`
+  ({pr}`599`, {user}`hyanwong`)
 
-********************
-[0.2.1] - 2021-05-26
-********************
+## [0.2.1] - 2021-05-26
 
 Bugfix release
 
 **Bugfixes**:
 
 - Fix a bug in the core LS matching algorithm in which the rate of recombination
-  was being incorrectly computed (:issue:`493`, :pr:`514`, :user:`jeromekelleher`,
-  :user:`hyanwong`).
+  was being incorrectly computed ({issue}`493`, {pr}`514`, {user}`jeromekelleher`,
+  {user}`hyanwong`).
 
-- ``tsinfer.verify()`` no longer requires that non-ancestral alleles in a SampleData
-  and Tree Sequence file are in the same order (:issue:`490`, :pr:`492`,
-  :user:`hyanwong`).
+- `tsinfer.verify()` no longer requires that non-ancestral alleles in a SampleData
+  and Tree Sequence file are in the same order ({issue}`490`, {pr}`492`,
+  {user}`hyanwong`).
 
 **New Features**:
 
 - Inferred ancestral haplotypes may be truncated via
-  ``AncestorData.truncate_ancestors()`` to improve performance when inferring large
-  datasets (:issue:`276`, :pr:`467`, :user:`awohns`).
+  `AncestorData.truncate_ancestors()` to improve performance when inferring large
+  datasets ({issue}`276`, {pr}`467`, {user}`awohns`).
 
 **Breaking changes**:
 
 - tsinfer now requires Python 3.7
 
 
-********************
-[0.2.0] - 2020-12-18
-********************
+## [0.2.0] - 2020-12-18
 
 Major feature release, including some incompatible file format and API updates.
 
@@ -101,17 +93,17 @@ Major feature release, including some incompatible file format and API updates.
   can now we be specified in the SampleData format. These will be included
   in the final tree sequence and allow for automatic decoding of JSON metadata.
 
-- Map non-inference sites onto the tree by using the tskit ``map_mutations``
+- Map non-inference sites onto the tree by using the tskit `map_mutations`
   parsimony method. This allows us to support sites with > 2 alleles.
 
 - Historical (non-contemporaneous) samples can now be accommodated in inference,
   assuming that the true dates of ancestors have been set, by using the concept
   of "proxy samples". This is done via the new function
-  ``AncestorData.insert_proxy_samples()``, then setting the new
-  parameter ``force_sample_times=True`` when matching samples.
+  `AncestorData.insert_proxy_samples()`, then setting the new
+  parameter `force_sample_times=True` when matching samples.
 
-- The default tree sequence returned after inference when ``simplify=True`` retains
-  unary nodes (i.e. simplify is done with ``keep_unary=True``.
+- The default tree sequence returned after inference when `simplify=True` retains
+  unary nodes (i.e. simplify is done with `keep_unary=True`.
 
 
 **Breaking changes**:
@@ -120,18 +112,18 @@ Major feature release, including some incompatible file format and API updates.
   0/1 values as before.
 
 - Times for undated sites now use frequencies (0..1), not as counts (1..num_samples),
-  and are now stored as ``tskit.UNKNOWN_TIME``, then calculated on the fly in the
+  and are now stored as `tskit.UNKNOWN_TIME`, then calculated on the fly in the
   variants() iterator.
 
-- The SampleData file no longer accepts the ``inference`` argument to add_site.
-  This functionality has been replaced by the ``exclude_positions`` argument
-  to the ``infer`` and ``generate_ancestors`` functions.
+- The SampleData file no longer accepts the `inference` argument to add_site.
+  This functionality has been replaced by the `exclude_positions` argument
+  to the `infer` and `generate_ancestors` functions.
 
 - The SampleData format is now at version 5, and older versions cannot be read.
   Users should rerun their data ingest pipelines.
 
-- Users can specify variant ages, via ``sample_data.add_sites(... , time=user_time)``.
-  If not ``None``, this overrides the default time position of an ancestor, otherwise
+- Users can specify variant ages, via `sample_data.add_sites(... , time=user_time)`.
+  If not `None`, this overrides the default time position of an ancestor, otherwise
   ancestors are ordered in time by using the frequency of the derived variant (#143).
 
 - Change "age" to "time" to match tskit/msprime notation, and to avoid confusion
@@ -140,37 +132,31 @@ Major feature release, including some incompatible file format and API updates.
 
 - Add the ability to record user-specified times for individuals, and therefore
   the samples contained in them (currently ignored during inference). Times are
-  added using ``sample_data.add_individual(... , time=user_time)`` (#190).
+  added using `sample_data.add_individual(... , time=user_time)` (#190).
 
-- Change ``tsinfer.UNKNOWN_ALLELE`` to ``tskit.MISSING_DATA`` for marking unknown regions
+- Change `tsinfer.UNKNOWN_ALLELE` to `tskit.MISSING_DATA` for marking unknown regions
   of ancestral haplotypes (#188) . This also involves changing the allele storage to a
-  signed int from ``np.uint8`` which matches the tskit v0.2 format for allele storage
+  signed int from `np.uint8` which matches the tskit v0.2 format for allele storage
   (see https://github.com/tskit-dev/tskit/issues/144).
 
 **Bugfixes**:
 
 - Individuals and populations in the SampleData file are kept in the returned tree
   sequence, even if they are not referenced by any sample. The individual and population
   ids are therefore guaranteed to stay the same between the sample data file and the
-  inferred tree sequence. (:pr:`348`)
+  inferred tree sequence. ({pr}`348`)
 
-********************
-[0.1.4] - 2018-12-12
-********************
+## [0.1.4] - 2018-12-12
 
 Bugfix release.
 
 - Fix issue caused by upstream changes in numcodecs (#136).
 
-********************
-[0.1.3] - 2018-11-02
-********************
+## [0.1.3] - 2018-11-02
 
 Release corresponding to code used in the preprint.
 
-********************
-[0.1.2] - 2018-06-18
-********************
+## [0.1.2] - 2018-06-18
 
 Minor update to take advantage of msprime 0.6.0's Population and Individual
 objects and fix various bugs.
@@ -182,7 +168,7 @@ objects and fix various bugs.
   of individuals and populations. Older SampleData files will not be
   readable and must be regenerated.
 
-- Changed the order of the ``alleles`` and ``genotypes`` arguments to
+- Changed the order of the `alleles` and `genotypes` arguments to
   SampleData.add_site.
 
 **New features**:

CITATION.md

@@ -0,0 +1,29 @@
+(sec_citation)=
+
+# Citing tsinfer
+
+If you use `tsinfer` in your work, please cite the
+[2019 Nature Genetics paper](<https://doi.org/10.1038/s41588-019-0483-y>):
+
+> Jerome Kelleher, Yan Wong, Anthony W. Wohns, 
+> Chaimaa Fadil, Patrick K. Albers & Gil McVean (2019) 
+> *Inferring whole-genome histories in large population datasets*,
+> Nature Genetics, Volume 51, 1330–1338. https://doi.org/10.1038/s41588-019-0483-y
+
+Bibtex record:
+
+```bibtex
+
+@article{Kelleher2019,
+  doi = {10.1038/s41588-019-0483-y},
+  url = {https://doi.org/10.1038/s41588-019-0483-y},
+  year = {2019},
+  month = sep,
+  publisher = {Springer Science and Business Media {LLC}},
+  volume = {51},
+  number = {9},
+  pages = {1330--1338},
+  author = {Jerome Kelleher and Yan Wong and Anthony W. Wohns and Chaimaa Fadil and Patrick K. Albers and Gil McVean},
+  title = {Inferring whole-genome histories in large population datasets},
+  journal = {Nature Genetics}
+}

README.md

@@ -1,11 +1,11 @@
 # tsinfer <img align="right" width="145" height="90" src="https://raw.githubusercontent.com/tskit-dev/tsinfer/main/docs/tsinfer_logo.svg">
 
-[![CircleCI](https://circleci.com/gh/tskit-dev/tsinfer.svg?style=svg)](https://circleci.com/gh/tskit-dev/tsinfer) [![Build Status](https://travis-ci.org/tskit-dev/tsinfer.svg?branch=main)](https://travis-ci.org/tskit-dev/tsinfer) [![Documentation Status](https://readthedocs.org/projects/tsinfer/badge/?version=latest)](http://tsinfer.readthedocs.io/en/latest/?badge=latest) [![codecov](https://codecov.io/gh/tskit-dev/tsinfer/branch/main/graph/badge.svg)](https://codecov.io/gh/tskit-dev/tsinfer)
+[![CircleCI](https://circleci.com/gh/tskit-dev/tsinfer.svg?style=svg)](https://circleci.com/gh/tskit-dev/tsinfer) [![Build Status](https://travis-ci.org/tskit-dev/tsinfer.svg?branch=main)](https://travis-ci.org/tskit-dev/tsinfer) [![Docs Build](https://github.com/tskit-dev/tsinfer/actions/workflows/docs.yml/badge.svg)](https://tskit.dev/tsinfer/docs/stable/introduction.html) [![codecov](https://codecov.io/gh/tskit-dev/tsinfer/branch/main/graph/badge.svg)](https://codecov.io/gh/tskit-dev/tsinfer)
 
 
 Infer a tree sequence from genetic variation data
 
-The [documentation](http://tsinfer.readthedocs.io/en/latest/) contains details of how to use this software, including [installation instructions](https://tsinfer.readthedocs.io/en/latest/installation.html).
+The [documentation](https://tskit.dev/tsinfer/docs/stable) contains details of how to use this software, including [installation instructions](https://tskit.dev/tsinfer/docs/stable/installation.html).
 
 The algorithm, its rationale, and results from testing on simulated and real data are described in the following [Nature Genetics paper](https://doi.org/10.1038/s41588-019-0483-y):
 

README.rst

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/CHANGELOG.md

@@ -0,0 +1 @@
+../CITATION.md