recap docs clarification and rtd fix

docs/conf.py

@@ -13,9 +13,14 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
+from unittest.mock import MagicMock
+
+MODULES = ['msprime']
+for mod_name in MODULES:
+    sys.modules[mod_name] = MagicMock()
 
 # -- Project information -----------------------------------------------------
 

docs/tutorial.rst

@@ -12,11 +12,13 @@ that we have run for 10,000 generations without neutral mutations.
 Now, we wish to extract whole-genome genotype data for only 1,000 individuals.
 A typical way to do this would be to
 
-1. :meth:`simplify` : For efficiency, subset the tree sequence to only the information relevant for those 1,000 individuals.
 
-2. :meth:`recapitate` : The simulation has likely not reached demographic equilibrium - it has not *coalesced* entirely;
+1. :meth:`recapitate` : The simulation has likely not reached demographic equilibrium - it has not *coalesced* entirely;
    recapitation uses coalescent simulation to provide a "prior history" for the initial generation of the simulation.
 
+1. :meth:`simplify` : For efficiency, subset the tree sequence to only the information relevant for those 1,000 individuals.
+   This needs to come *after* simplification.
+
 3. :meth:`mutate` : This adds neutral mutations on top of the tree sequence.
 
 These steps are described below.

docs/vignette_space.rst

@@ -550,9 +550,9 @@ than most modern ones are from each other.
 
 
 
-*****************************
-Simplification and VCF output
-*****************************
+**********
+VCF output
+**********
 
 Now we want to write out these data for analysis with other programs.
 To do this, and make sure that everything stays nicely cross-referenced,

pyslim/slim_tree_sequence.py

@@ -307,6 +307,9 @@ def recapitate(self, recombination_rate, keep_first_generation=False,
         If you want to keep them, then set ``keep_first_generation`` to True;
         although this will make more work here.
 
+        This also means that you must *not* simplify before you recapitate your
+        SLiM-produced tree sequence.
+
         Note that ``Ne`` is not set automatically, so defaults to ``1.0``; you probably
         want to set it explicitly.  Similarly, migration is not set up
         automatically, so that if there are uncoalesced lineages in more than

requirements/conda-minimal.txt

@@ -0,0 +1,5 @@
+tskit
+msprime
+kastore
+attr
+numpy

requirements/rtd.txt

@@ -0,0 +1,4 @@
+tskit
+kastore
+attr
+numpy