Update docs (#590)

Author: jrbourbeau

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: doc/source/conf.py
+  # Temporarily turning off to get docs build passing
+  # fail_on_warning: true
+
+python:
+  install:
+    - requirements: doc/requirements.txt
+    - method: pip
+      path: .

doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+furo

doc/source/conf.py

@@ -93,7 +93,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'furo'
 
 # 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
@@ -105,7 +105,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = "Toolz"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None

doc/source/heritage.rst

@@ -2,13 +2,13 @@ Heritage
 ========
 
 While Python was originally intended as an imperative language
-[Guido_], it contains all elements necessary to support a rich set of features
+[`Guido`_], it contains all elements necessary to support a rich set of features
 from the functional paradigm.  In particular its core data structures, lazy
 iterators, and functions as first class objects can be combined to implement a
 common standard library of functions shared among many functional languages.
 
 This was first recognized and supported through the standard libraries
-itertools_ and functools_ which contain functions like ``permutations``,
+itertools_ and `functools`_ which contain functions like ``permutations``,
 ``chain`` and ``partial`` to complement the standard ``map``, ``filter``,
 ``reduce`` already found in the core language.  While these libraries contain
 substantial functionality they do not achieve the same level of adoption found
@@ -17,35 +17,31 @@ incomplete and lack a number of commonly related functions like ``compose`` and
 ``groupby`` which often complement these core operations.
 
 A completion of this set of functions was first attempted in the projects
-itertoolz_ and functoolz_ (note the z).  These libraries contained
-several functions that were absent in the standard itertools_/functools_
+`itertoolz`_ and `functoolz`_ (note the z).  These libraries contained
+several functions that were absent in the standard itertools_ / `functools`_
 libraries.  The ``itertoolz``/``functoolz`` libraries were eventually merged
 into the monolithic ``toolz`` project described here.
 
 Most contemporary functional languages (Haskell, Scala, Clojure, ...) contain
 some variation of the functions found in ``toolz``.  The ``toolz`` project
 generally adheres closely to the API found in the Clojure standard library (see
-cheatsheet_) and where disagreements occur that API usually dominates.  The
+`cheatsheet`_) and where disagreements occur that API usually dominates.  The
 ``toolz`` API is also strongly affected by the principles of the Python
 language itself, and often makes deviations in order to be more approachable to
 that community.
 
 The development of a functional standard library within a popular imperative
 language is not unique.  Similar projects have arisen in other
 imperative-by-design languages that contain the necessary elements to support a
-functional standard library.  Underscore.js_ in JavaScript has attained
+functional standard library.  `Underscore.js <https://underscorejs.org>`_ in JavaScript has attained
 notable popularity in the web community.  ``LINQ`` in C# follows a similar
 philosophy but mimics declarative database languages rather than functional
-ones.  Enumerable_ is is the closest project in Ruby.  Other excellent projects
-also exist within the Python ecosystem, most notably Fn.py_ and Funcy_.
+ones. `Enumerable <https://ruby-doc.org/core-2.0.0/Enumerable.html>`_ is is the closest project in Ruby.  Other excellent projects
+also exist within the Python ecosystem, most notably `Fn.py <https://github.com/kachayev/fn.py>`_ and `Funcy <https://github.com/suor/funcy/>`_.
 
-.. [itertools] https://docs.python.org/2/library/itertools.html
-.. [functools] https://docs.python.org/2/library/functools.html
-.. [itertoolz] https://github.com/mrocklin/itertoolz
-.. [functoolz] https://github.com/mrocklin/functoolz
-.. [Underscore.js] https://underscorejs.org
-.. [cheatsheet] https://clojure.org/cheatsheet
-.. [Guido] https://python-history.blogspot.com/2009/04/origins-of-pythons-functional-features.html
-.. [Enumerable] https://ruby-doc.org/core-2.0.0/Enumerable.html
-.. [funcy] https://github.com/suor/funcy/
-.. [fn.py] https://github.com/kachayev/fn.py
+.. _itertools: https://docs.python.org/library/itertools.html
+.. _functools: https://docs.python.org/library/functools.html
+.. _itertoolz: https://github.com/mrocklin/itertoolz
+.. _functoolz: https://github.com/mrocklin/functoolz
+.. _cheatsheet: https://clojure.org/cheatsheet
+.. _Guido: https://python-history.blogspot.com/2009/04/origins-of-pythons-functional-features.html

doc/source/install.rst

@@ -11,4 +11,4 @@ three ways:
 
 1.  Toolz is pure Python
 2.  Toolz relies only on the standard library
-3.  Toolz simultaneously supports Python versions 3.5+ and PyPy
+3.  Toolz simultaneously supports Python versions 3.8+ and PyPy

doc/source/laziness.rst

@@ -9,8 +9,9 @@ memory.  They act like lists but don't take up space.
 Example - A Tale of Two Cities
 ------------------------------
 
-We open a file containing the text of the classic text "A Tale of Two Cities"
-by Charles Dickens[1_].
+We open `a file <http://www.gutenberg.org/cache/epub/98/pg98.txt>`_ containing
+the text of the classic text "A Tale of Two Cities"
+by Charles Dickens.
 
 .. code::
 
@@ -98,6 +99,4 @@ In this case ``frequencies`` is a sort of reduction.  At no time were more than
 a few hundred bytes of Tale of Two Cities necessarily in memory.  We could just
 have easily done this computation on the entire Gutenberg collection or on
 Wikipedia.  In this case we are limited by the size and speed of our hard drive
-and not by the capacity of our memory.
-
-.. [1] http://www.gutenberg.org/cache/epub/98/pg98.txt
+and not by the capacity of our memory.

toolz/itertoolz.py

@@ -817,6 +817,7 @@ def join(leftkey, leftseq, rightkey, rightseq,
     This is a semi-streaming operation.  The LEFT sequence is fully evaluated
     and placed into memory.  The RIGHT sequence is evaluated lazily and so can
     be arbitrarily large.
+
     (Note: If right_default is defined, then unique keys of rightseq
         will also be stored in memory.)
 

toolz/sandbox/parallel.py

@@ -14,10 +14,18 @@ def fold(binop, seq, default=no_default, map=map, chunksize=128, combine=None):
     """
     Reduce without guarantee of ordered reduction.
 
+    Parameters
+    ----------
+    binops
+        Associative operator. The associative property allows us to
+        leverage a parallel map to perform reductions in parallel.
+
+
     inputs:
 
     ``binop``     - associative operator. The associative property allows us to
                     leverage a parallel map to perform reductions in parallel.
+
     ``seq``       - a sequence to be aggregated
     ``default``   - an identity element like 0 for ``add`` or 1 for mul