Merge pull request #329 from hyanwong/docs-rejig

Restructure all docs into JupyterBook format

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Build Docs
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags:
+      - '*'
+
+env:
+  COMMIT_EMAIL: ben.jeffery.well+adminbot@gmail.com
+  OWNER: tskit-dev
+  REPO: tsdate
+  REQUIREMENTS: docs/requirements.txt
+
+jobs:
+  build-deploy-docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
+
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+
+      - name: Create venv and install deps
+        run: |
+          pip install --upgrade pip wheel
+          pip install -r ${{env.REQUIREMENTS}}          
+
+      - name: Build Docs
+        run: |
+          make -C docs
+
+      - 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"}'

.mergify.yml

@@ -0,0 +1,31 @@
+queue_rules:
+  - name: default
+    conditions:
+      - "#approved-reviews-by>=1"
+      - "#changes-requested-reviews-by=0"
+      - "status-success=ci/circleci: build"
+      - status-success=Docs
+pull_request_rules:
+  - name: Automatic rebase, CI and merge
+    conditions:
+      - "-merged"
+      - "#approved-reviews-by>=1"
+      - "#changes-requested-reviews-by=0"
+      - base=main
+      - label=AUTOMERGE-REQUESTED
+      - "status-success=ci/circleci: build"
+      - status-success=Docs
+    actions:
+      queue:
+        name: default
+        method: rebase
+        update_method: rebase
+
+  - name: Remove label after merge
+    conditions:
+      - merged
+      - label=AUTOMERGE-REQUESTED
+    actions:
+      label:
+        remove:
+          - AUTOMERGE-REQUESTED

CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+## [0.1.6] - ****-**-**
+
+**Breaking changes**
+
+- The standalone `preprocess_ts` function now defaults to not removing unreferenced
+  individuals, populations, or sites, aiming to change the tree sequence tables as
+  little as possible.
+
+- Not strictly breaking, as not in the published API, but the "normalize" flag
+  in `get_dates` and the internal `normalize` terminology is changed to
+  `standardize` to better reflect the fact that the maximum (not sum) is one.
+
+- The `Ne` argument to `date` has been deprecated (although it is
+  still in the API for backward compatibility).  The equivalent argument
+  `population_size` should be used instead.
+
+- The CLI `-verbosity` flag no longer takes a number, but uses
+  `action="count"`, so `-v` turns verbosity to INFO level,
+  whereas `-vv` turns verbosity to DEBUG level.
+
+**Features**
+
+- Priors may be calculated using a piecewise-constant effective population trajectory,
+  which is implemented in the `demography.PopulationSizeHistory` class. The
+  `population_size` argument to `date` accepts either a single scalar effective
+  population size, or a `PopulationSizeHistory` instance.
+
+**Bugfixes**
+
+- The returned posteriors when `return_posteriors=True` now return actual
+  probabilities (scaled so that they sum to one) rather than standardized
+  "probabilities" whose maximum value is one.
+
+- The population size is saved in provenance metadata when possible (e.g. if it is
+  a single number)
+
+- `preprocess_ts` always records provenance as being from the `preprocess_ts`
+  command, even if no gaps are removed. The command now has a (rarely used)
+  `delete_intervals` parameter, which is normally filled out and saved in provenance
+  (as it was before). If no gap deletion is done, the param is saved as `[]`
+
+
+## [0.1.5] - 2022-06-07
+
+**Features**
+
+- Added the `time_units` parameter to `tsdate.date`, allowing users to specify
+  the time units of the dated tree sequence. Default is `"generations"`.
+- Added the `return_posteriors` parameter to `tsdate.date`. If True, the function
+  returns a tuple of `(dated_ts, posteriors)`.
+- `mutation_rate` is now a required argument in `tsdate.date` and `tsdate.get_dates`
+- tsdate returns an error if users attempt to date an unsimplified tree sequence.
+- Updated tsdate citation information to cite the recent Science paper
+- Built wheel on Python 3.10
+
+
+## [0.1.4] - 2021-06-30
+
+**Features**
+
+- The algorithm now operates completely in unscaled time (in units of generations) under
+  the hood, which means that `tsdate.build_prior_grid` now requires the parameter
+  `Ne`.
+- Users now have access to the marginal posterior distributions on node age by running 
+  `tsdate.get_dates`, though this is undocumented for now.
+
+**Bugfixes**
+
+- A fix to the way likelihoods are added should eliminate numerical errors that are
+  sometimes encountered when dating very large tree sequences.
+
+
+## [0.1.3] - 2021-02-15
+
+**Features**
+
+- Two new methods, `tsdate.sites_time_from_ts` and `tsdate.add_sampledata_times`, 
+  support inference of tree sequences from non-contemporaneous samples.
+- New tutorial on inferring tree sequences from modern and historic/ancient samples 
+  explains how to use these functions in conjunction with `tsinfer`.
+- `tsdate.preprocess_ts` supports dating inferred tree sequences which include large, 
+  uninformative stretches (i.e. centromeres and telomeres). Simply run this function 
+  on the tree sequence before dating it.
+- `ignore_outside` is a new parameter in the outside pass which tells `tsdate` to 
+  ignore edges from oldest root (these edges are often of low quality in `tsinfer`
+  inferred tree sequences)
+- Development environment is now equivalent to other `tskit-dev` projects
+
+
+## [0.1.2] - 2020-02-28
+
+- Improve user experience with more progress bars and logging.
+- Slightly change traversal method in outside and outside maximization algorithms,
+  this should only affect inference on inferred tree sequences with large numbers 
+  of nodes at the same frequency.
+- Improve reporting of current project version
+- Use appdirs for default caching location
+- Prevent dating tree sequences with dangling nodes
+
+
+
+## [0.1.1] - 2020-02-25
+
+- Bugfix release: resolve issue with precalculating prior values.
+
+
+€# [0.1.0] - 2020-02-24
+
+Early Alpha release made available via PyPI for community testing and evaluation.
+
+Please don't use this version in published works.
+
+

docs/CHANGELOG.md

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

docs/Makefile

@@ -1,24 +1,19 @@
-# Minimal makefile for Sphinx documentation
-#
+# Need to set PYTHONPATH so that we pick up the local tsdate
+PYPATH=$(shell pwd)/../
+TSDATE_VERSION:=$(shell PYTHONPATH=${PYPATH} \
+   python3 -c 'import tsdate; print(tsdate.__version__.split("+")[0])')
 
-# You can set these variables from the command line.
-SPHINXOPTS    = #-W
-SPHINXBUILD   = python3 -m sphinx
-SOURCEDIR     = .
 BUILDDIR      = _build
 
-all:
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+all: dev
 
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+dev:
+	PYTHONPATH=${PYPATH} ./build.sh
 
-clean:
-	rm -rf $(BUILDDIR)
-
-.PHONY: help Makefile
+dist:
+	@echo Building distribution for tsdate version ${TSDATE_VERSION}
+	sed -i -e s/__TSDATE_VERSION__/${TSDATE_VERSION}/g _config.yml
+	PYTHONPATH=${PYPATH} ./build.sh
 
-# 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)
+clean:
+	rm -fR $(BUILDDIR)