fix docs

hail/python/hail/context.py

@@ -825,15 +825,22 @@ def get_reference(name) -> ReferenceGenome:
 
 @typecheck(seed=int)
 def set_global_seed(seed):
-    """Sets Hail's global seed to `seed`.
+    """Deprecated.
+
+    Has no effect. To ensure reproducible randomness, use the `global_seed`
+    argument to :func:`.init` and :func:`.reset_global_randomness`.
+
+    See the :ref:`random functions <sec-random-functions>` reference docs for more.
 
     Parameters
     ----------
     seed : :obj:`int`
         Integer used to seed Hail's random number generator
     """
 
-    # FIXME: print deprecation warning
+    warning('hl.set_global_seed has no effect. See '
+            'https://hail.is/docs/0.2/functions/random.html for details on '
+            'ensuring reproducibility of randomness.')
     pass
 
 

hail/python/hail/docs/api.rst

@@ -56,5 +56,6 @@ Top-Level Functions
 .. autofunction:: hail.default_reference
 .. autofunction:: hail.get_reference
 .. autofunction:: hail.set_global_seed
+.. autofunction:: hail.reset_global_randomness
 .. autofunction:: hail.citation
 .. autofunction:: hail.version

hail/python/hail/docs/functions/random.rst

@@ -1,3 +1,5 @@
+.. _sec-random-functions:
+
 Random functions
 ----------------
 
@@ -94,6 +96,7 @@ return the same result, e.g.
 
 However, moving it to a sufficiently different context will produce different
 results:
+
     >>> table = hl.utils.range_table(7, 1)
     >>> table = table.filter(table.idx >= 2).annotate(x=hl.rand_unif(0, 1, seed=0))
     >>> table.x.collect()
@@ -104,6 +107,7 @@ results:
      0.5550464170615771]
 
 In fact, in this case we are getting the tail of
+
     >>> table = hl.utils.range_table(7, 1).annotate(x=hl.rand_unif(0, 1, seed=0))
     >>> table.x.collect()
     [0.5820244750020055,
@@ -118,28 +122,20 @@ Reproducibility across sessions
 ===============================
 
 The values of a random function are fully determined by three things:
+
 * The seed set on the function itself. If not specified, these are simply
   generated sequentially.
 * Some data uniquely identifying the current position within a larger context,
   e.g. Table, MatrixTable, or array. For instance, in a :func:`.range_table`,
   this data is simply the row id, as suggested by the previous examples.
 * The global seed. This is fixed for the entire session, and can only be set
-  using the `global_seed` argument to :func:`.init`.
+  using the ``global_seed`` argument to :func:`.init`.
 
 To ensure reproducibility within a single hail session, it suffices to either
 manually set the seed on every random function call, or to call
 :func:`.reset_global_randomness` at the start of a pipeline, which resets the
 counter used to generate seeds.
 
-To ensure reproducibility across sessions, one must in addition specify the
-`global_seed` in :func:`.init`. If not specified, the global seed is chosen
-randomly.
-
-
-The seed can also be set globally using :func:`.set_global_seed`. This sets the
-seed globally for all subsequent Hail operations, and a pipeline will be
-guaranteed to have the same results if the global seed is set right beforehand:
-
     >>> hl.reset_global_randomness()
     >>> hl.eval(hl.array([hl.rand_unif(0, 1), hl.rand_unif(0, 1)]))
     [0.9828239225846387, 0.49094525115847415]
@@ -148,6 +144,14 @@ guaranteed to have the same results if the global seed is set right beforehand:
     >>> hl.eval(hl.array([hl.rand_unif(0, 1), hl.rand_unif(0, 1)]))
     [0.9828239225846387, 0.49094525115847415]
 
+To ensure reproducibility across sessions, one must in addition specify the
+`global_seed` in :func:`.init`. If not specified, the global seed is chosen
+randomly. All documentation examples were computed using ``global_seed=0``.
+
+    >>> hl.stop()                                               # doctest: +SKIP
+    >>> hl.init(global_seed=0)
+    >>> hl.eval(hl.array([hl.rand_unif(0, 1), hl.rand_unif(0, 1)]))
+    [0.9828239225846387, 0.49094525115847415]
 
 .. autosummary::
 

hail/python/hail/expr/functions.py

@@ -2492,7 +2492,7 @@ def rand_norm(mean=0, sd=1, seed=None, size=None) -> Float64Expression:
         Standard deviation of normal distribution.
     seed : :obj:`int`, optional
         Random seed.
-    size : :obj:`int` or :ojb:`tuple` of :obj:`int`, optional
+    size : :obj:`int` or :obj:`tuple` of :obj:`int`, optional
 
     Returns
     -------
@@ -2621,7 +2621,7 @@ def rand_unif(lower=0.0, upper=1.0, seed=None, size=None) -> Float64Expression:
         Right boundary of range. Defaults to 1.0.
     seed : :obj:`int`, optional
         Random seed.
-    size : :obj:`int` or :ojb:`tuple` of :obj:`int`, optional
+    size : :obj:`int` or :obj:`tuple` of :obj:`int`, optional
 
     Returns
     -------