update documentation

doc/examples/precapitation.rst

@@ -3,6 +3,10 @@
 Starting a simulation with a tree sequence from msprime
 ================================================================================
 
+.. todo::
+
+   Document what to do with discrete crossover positions
+
 The following command line uses :mod:`msprime` to simulate under the discrete
 time Wright-Fisher model using the methods described in [Nelson2020]_.  Then,
 `fwdpy11` simulates for another 1,000 generations.  From the end of each simulation,

doc/examples/recapitation.rst

@@ -3,6 +3,10 @@
 Finishing a simulation with a tree sequence from msprime
 ================================================================================
 
+.. todo::
+
+   Document what to do with discrete crossover positions
+
 This example is complementary to :ref:`precapitation`.  Rather than starting
 with a tree sequence from :mod:`msprime`, we instead finish a simulation by "coalescing
 back" the first generation of the simulation using :mod:`msprime`.  [Haller2019]_

doc/pages/tutorial.rst

@@ -397,6 +397,28 @@ one-half, meaning that each region is assorting independently (50 `cM` between e
 
 As an aside, this example is not creating objects in order by their positions.  Such ordering is not required.
 
+Beginning in version ``0.12.0``, it is possible to restrict crossover positions to integer values.
+For the examples given above, crossover positions are floating-point values sampled uniformly from :math:`[beg, end)`.
+To restrict positions to integer values, we pass ``discrete=True`` when creating object instances:
+
+.. jupyter-execute::
+
+    recregions = [
+        fwdpy11.PoissonInterval(beg=0, end=5, mean=2e-3 / 3, discrete=True),
+        fwdpy11.PoissonInterval(beg=5, end=10, mean=1e-3 / 3, discrete=True),
+    ]
+
+Now, breakpoints from the first region will only take on values of ``0``, ``1``, ``2``, ``3``, or ``4``.
+
+Setting ``discrete=True`` requires the following:
+
+* Values for ``beg`` and ``end`` must be :class:`int`.  Thus, ``1`` is valid but ``1.0`` will raise a ``TypeError``.
+* ``end - beg`` must be ``> 1``.  This requirement prevents you from using ``beg=0`` and ``end=1``, for example,
+  which would result in the only possible crossover position being ``0``.
+* You must be more careful when using :mod:`msprime` to start/finish a simulation.
+  See :ref:`here <precapitation>` and :ref:`here <recapitation>` for details.
+
+
 The following classes are available:
 
 * :class:`fwdpy11.PoissonInterval`