DOC: Improve documentation

Improve documentation appearance
Fix setup to not cythonize when run with clean

Author: Sheppard, Kevin

doc/source/_static/style-changes.css

@@ -1,2 +1,7 @@
 a{color: #180CD2;}
-table a:not(.btn), .table a:not(.btn) {text-decoration: none;}
+table a:not(.btn), .table a:not(.btn) {text-decoration: none;}
+body {font-size: 16px;}
+code {font-size: 100%;}
+table {font-size: 16px;}
+.navbar {font-size: 16px;}
+.navbar .dropdown-menu > li > a, .navbar .dropdown-menu > li > a:focus {font-size: 15px;}

doc/source/conf.py

@@ -129,7 +129,9 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {'bootswatch_theme': 'flatly'}
+html_theme_options = {'bootswatch_theme': 'yeti',
+                      # Render the next and previous page links in navbar. (Default: true)
+                      'navbar_sidebarrel': False,}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

doc/source/index.rst

@@ -68,7 +68,7 @@ RandomState Pseudo Random Number Generator Documentation:
    PCG-64 <pcg64>
    MLFG <mlfg>
    MRG32K3A <mrg32k3a>
-   Readying System Entropy <entropy>
+   Reading System Entropy <entropy>
 
 
 Indices and tables

randomstate/shims/mlfg-1279-861/mlfg-1279-861.pxi

@@ -50,9 +50,9 @@ cdef object _set_state(aug_state *state, object state_info):
 DEF CLASS_DOCSTRING = """
 RandomState(seed=None)
 
-Container for a multiplicative lagged fibonacci generator (MLFG).
+Container for a Multiplicative Lagged Fibonacci Generator (MLFG).
 
-MLFG(1279, 861, \*) is a 64-bit implementation of a MLFG that uses lags 1279 and
+LFG(1279, 861, \*) is a 64-bit implementation of a MLFG that uses lags 1279 and
 861 where random numbers are determined by
 
 .. math::

randomstate/shims/pcg-32/pcg-32.pxi

@@ -85,22 +85,22 @@ The state of the PCG-32 PRNG is represented by 2 64-bit unsigned integers.
 
 See pcg64 for a similar implementation with a larger period.
 
-** Parallel Features **
+**Parallel Features**
 
 ``pcg32.RandomState`` can be used in parallel applications in one of two ways.
 The preferable method is to use sub-streams, which are generated by using the
-same value in the first position of the seed and incrementing the second value.
+same value of ``seed`` and incrementing the second value, ``inc``.
 
 >>> import randomstate.prng.pcg32 as rnd
 >>> rs = [rng.RandomState(1234, i + 1) for i in range(10)]
 
-The alternative method is to use a single RandomState and advance to get
-non-overlapping sequences.
+The alternative method is to call ``advance`` on a single RandomState to
+produce non-overlapping sequences.
 
 >>> import randomstate.prng.pcg32 as rnd
 >>> rs = [rng.RandomState(1234, 1) for _ in range(10)]
 >>> for i in range(10):
-        rs[i].advance(2**32)
+        rs[i].advance(i * 2**32)
 
 *Note*: Due to the limited period of ``pcg32.RandomState``  using ``advance``
 in parallel applications is not recommended.

randomstate/shims/pcg-64/pcg-64-docstring.pxi

@@ -45,22 +45,22 @@ The state of the PCG-64 PRNG is represented by 2 128-bit unsigned integers.
 
 See pcg32 for a similar implementation with a smaller period.
 
-** Parallel Features **
+**Parallel Features**
 
 ``pcg64.RandomState`` can be used in parallel applications in one of two ways.
 The preferable method is to use sub-streams, which are generated by using the
-same value in the first position of the seed and incrementing the second value.
+same value of ``seed`` and incrementing the second value, ``inc``.
 
 >>> import randomstate.prng.pcg64 as rnd
 >>> rs = [rng.RandomState(1234, i + 1) for i in range(10)]
 
-The alternative method is to use a single RandomState and advance to get
-non-overlapping sequences.
+The alternative method is to call ``advance`` on a single RandomState to
+produce non-overlapping sequences.
 
 >>> import randomstate.prng.pcg64 as rnd
 >>> rs = [rng.RandomState(1234, 1) for _ in range(10)]
 >>> for i in range(10):
-        rs[i].advance(2**32)
+        rs[i].advance(i * 2**64)
 
 References
 ----------

randomstate/shims/xorshift1024/xorshift1024.pxi

@@ -54,9 +54,9 @@ RandomState(seed=None)
 Container for the xorshift1024* pseudo random number generator.
 
 xorshift1024* is a 64-bit implementation of Saito and Matsumoto's XSadd
-generator [1]_. xorshift1024* has a period of 2**1024 - 1 and supports jumping
-the sequence in increments of 2**512, which allow multiple non-overlapping
-sequences to be generated.
+generator [1]_,[2]_,[3]_,[4]_. xorshift1024* has a period of 2**1024 - 1 and
+supports jumping the sequence in increments of 2**512, which allow multiple
+non-overlapping sequences to be generated.
 
 ``xorshift1024.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. In addition to the
@@ -88,11 +88,13 @@ Notes
 -----
 See xorshift128 for a faster implementation that has a smaller period.
 
-** Parallel Features **
+**Parallel Features**
 
 ``xorshift1024.RandomState`` can be used in parallel applications by
-invoking the ``xorshift1024.RandomState.jump`` which will advance the
-the state as-if :math:`2^512` random numbers have been generated.
+calling the method ``jump`` which advances the
+the state as-if :math:`2^{512}` random numbers have been generated. This
+allow the original sequence to be split so that distinct segments can be used
+on each worker process.
 
 >>> import randomstate.prng.xorshift1024 as rnd
 >>> rs = [rnd.RandomState(1234) for _ in range(10)]
@@ -104,4 +106,10 @@ References
 ----------
 .. [1] "xorshift*/xorshift+ generators and the PRNG shootout",
        http://xorshift.di.unimi.it/
+.. [2] Marsaglia, George. "Xorshift RNGs." Journal of Statistical Software
+       [Online], 8.14, pp. 1 - 6, .2003.
+.. [3] Sebastiano Vigna. "An experimental exploration of Marsaglia's xorshift
+       generators, scrambled." CoRR, abs/1402.6246, 2014.
+.. [4] Sebastiano Vigna. "Further scramblings of Marsaglia's xorshift
+       generators." CoRR, abs/1403.0930, 2014.
 """

randomstate/shims/xorshift128/xorshift128.pxi

@@ -49,9 +49,9 @@ RandomState(seed=None)
 Container for the xorshift128+ pseudo random number generator.
 
 xorshift128+ is a 64-bit implementation of Saito and Matsumoto's XSadd
-generator [1]_. xorshift128+ has a period of 2**128 - 1 and supports jumping
-the sequence in increments of 2**64, which allow multiple non-overlapping
-sequences to be generated.
+generator [1]_,[2]_,[3]_,[4]_. xorshift128+ has a period of 2**128 - 1 and
+supports jumping the sequence in increments of 2**64, which allow multiple
+non-overlapping sequences to be generated.
 
 ``xorshift128.RandomState`` exposes a number of methods for generating random
 numbers drawn from a variety of probability distributions. In addition to the
@@ -84,11 +84,13 @@ Notes
 See xorshift1024 for an implementation with a larger period
 (2**1024 - 1) and jump size.
 
-** Parallel Features **
+**Parallel Features**
 
 ``xorshift128.RandomState`` can be used in parallel applications by
-invoking the ``xorshift128.RandomState.jump`` which will advance the
-the state as-if :math:`2^64` random numbers have been generated.
+calling the method ``jump`` which advances the
+the state as-if :math:`2^{64}` random numbers have been generated. This
+allow the original sequence to be split so that distinct segments can be used
+on each worker process.
 
 >>> import randomstate.prng.xorshift128 as rnd
 >>> rs = [rnd.RandomState(1234) for _ in range(10)]
@@ -100,4 +102,10 @@ References
 ----------
 .. [1] "xorshift*/xorshift+ generators and the PRNG shootout",
        http://xorshift.di.unimi.it/
+.. [2] Marsaglia, George. "Xorshift RNGs." Journal of Statistical Software
+       [Online], 8.14, pp. 1 - 6, .2003.
+.. [3] Sebastiano Vigna. "An experimental exploration of Marsaglia's xorshift
+       generators, scrambled." CoRR, abs/1402.6246, 2014.
+.. [4] Sebastiano Vigna. "Further scramblings of Marsaglia's xorshift
+       generators." CoRR, abs/1403.0930, 2014.
 """

setup.py

@@ -184,6 +184,11 @@ def is_pure(self):
                     extra_link_args=extra_link_args)
     extensions.append(ext)
 
+# Do not run cythonize if clean
+if 'clean' in sys.argv:
+    def cythonize(e):
+        return e
+
 ext_modules = cythonize(extensions)
 
 classifiers = ['Development Status :: 5 - Production/Stable',
@@ -231,7 +236,9 @@ def is_pure(self):
       zip_safe=False)
 
 # Clean up generated files
+exts = ('.pyx', '-config.pxi', '.c')
 for config in configs:
-    os.unlink(join(mod_dir, config['file_name'] + '.pyx'))
-    os.unlink(join(mod_dir, config['file_name'] + '-config.pxi'))
-    os.unlink(join(mod_dir, config['file_name'] + '.c'))
+    for ext in exts:
+        file_path = join(mod_dir, config['file_name'] + ext)
+        if os.path.exists(file_path):
+            os.unlink(file_path)