Working on the Sphinx docs.

I had to remove the tuples from the args specs, sphinx had kittens.

I see value both in the autodoc for library.py and the library examples
Jupyter notebook (converted to ReST format) so I'm including them both.

Calling the library module autodocs the "Function Reference".

Makefile

@@ -26,3 +26,4 @@ test: sdist
 docs:
 	cd ./docs && python -m nbconvert --to html *.ipynb
 	cd ./docs && python -m nbconvert --to markdown *.ipynb
+	cd ./docs && python -m nbconvert --to rst *.ipynb

docs/Advent of Code 2017 December 3rd.html

@@ -12600,7 +12600,7 @@ $$4 k \left(k + 1\right) + 2$$
 <div class="prompt input_prompt">In&nbsp;[19]:</div>
 <div class="inner_cell">
     <div class="input_area">
-<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="k">time</span> rank_of(23000000000000)  # Compare runtime with rank_and_offset()!
+<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="n">time</span> <span class="n">rank_of</span><span class="p">(</span><span class="mi">23000000000000</span><span class="p">)</span>  <span class="c1"># Compare runtime with rank_and_offset()!</span>
 </pre></div>
 
 </div>
@@ -12645,7 +12645,7 @@ $$2397916$$
 <div class="prompt input_prompt">In&nbsp;[20]:</div>
 <div class="inner_cell">
     <div class="input_area">
-<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="k">time</span> rank_and_offset(23000000000000)
+<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="n">time</span> <span class="n">rank_and_offset</span><span class="p">(</span><span class="mi">23000000000000</span><span class="p">)</span>
 </pre></div>
 
 </div>
@@ -12911,7 +12911,7 @@ $$\lfloor{\frac{1}{2} \sqrt{y - 1} - \frac{1}{2}}\rfloor + 1$$
 <div class="prompt input_prompt">In&nbsp;[28]:</div>
 <div class="inner_cell">
     <div class="input_area">
-<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="k">time</span> int(F(23000000000000))  # The clear winner.
+<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="n">time</span> <span class="nb">int</span><span class="p">(</span><span class="n">F</span><span class="p">(</span><span class="mi">23000000000000</span><span class="p">))</span>  <span class="c1"># The clear winner.</span>
 </pre></div>
 
 </div>
@@ -12981,7 +12981,7 @@ $$2397916$$
 <div class="prompt input_prompt">In&nbsp;[30]:</div>
 <div class="inner_cell">
     <div class="input_area">
-<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="k">time</span> mrank_of(23000000000000)
+<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="n">time</span> <span class="n">mrank_of</span><span class="p">(</span><span class="mi">23000000000000</span><span class="p">)</span>
 </pre></div>
 
 </div>
@@ -13227,7 +13227,7 @@ $$4572225$$
 <div class="prompt input_prompt">In&nbsp;[37]:</div>
 <div class="inner_cell">
     <div class="input_area">
-<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="k">time</span> aoc20173(23000000000000000000000000)  # Fast for large values.
+<div class=" highlight hl-ipython2"><pre><span></span><span class="o">%</span><span class="n">time</span> <span class="n">aoc20173</span><span class="p">(</span><span class="mi">23000000000000000000000000</span><span class="p">)</span>  <span class="c1"># Fast for large values.</span>
 </pre></div>
 
 </div>

docs/sphinx_docs/conf.py

@@ -24,7 +24,7 @@ copyright = u'2018, Simon Forman'
 author = u'Simon Forman'
 
 # The short X.Y version
-version = u''
+version = u'0.1'
 # The full version, including alpha/beta/rc tags
 release = u'0.1.0'
 

docs/sphinx_docs/index.rst

@@ -3,21 +3,44 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Thun Documentation
+Thun |release| Documentation
-==================
+============================
+
+Thun is dialect of Joy written in Python.
+
+Joy is a programming language created by Manfred von Thun that is easy to
+use and understand and has many other nice properties.  This Python
+package implements an interpreter for a dialect of Joy that attempts to
+stay very close to the spirit of Joy but does not precisely match the
+behaviour of the original version(s) written in C.  The main difference
+between Thun and the originals, other than being written in Python, is
+that it works by the "Continuation-Passing Style".
+
+
+Quick Start
+--------------------------------------------------
+
+Install from PyPI in the usual way::
+
+    $ pip install Thun
+
+To start the REPL::
+
+    $ python -m joy
+
 
-Hey there!
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   joy
    stack
    parser
    pretty
+   library
+   lib
 
-.. automodule:: joy.joy
-   :members:
 
 
 Indices and tables

docs/sphinx_docs/joy.rst

@@ -0,0 +1,9 @@
+
+Joy Interpreter
+===============
+
+
+.. automodule:: joy.joy
+   :members:
+
+

docs/sphinx_docs/library.rst

@@ -1,9 +1,9 @@
 
-Functions, Combinators and Definitions
+Function Reference
 ======================================
 
 
-. . automodule:: joy.library
+.. automodule:: joy.pribrary
    :members:
 
 

joy/joy.py

@@ -1,53 +1,26 @@
 # -*- coding: utf-8 -*-
+#
+#    Copyright © 2014, 2015, 2017, 2018 Simon Forman
+#
+#    This file is part of Thun
+#
+#    Thun is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    Thun is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with Thun.  If not see <http://www.gnu.org/licenses/>.
+#
 '''
-
+This module implements an interpreter for a dialect of Joy that
-
+attempts to stay very close to the spirit of Joy but does not precisely
-A dialect of Joy in Python.
+match the behaviour of the original version(s) written in C.
-
-
-Joy is a programming language created by Manfred von Thun that is easy to
-use and understand and has many other nice properties.  This Python script
-is an interpreter for a dialect of Joy that attempts to stay very close
-to the spirit of Joy but does not precisely match the behaviour of the
-original version(s) written in C.  A Tkinter GUI is provided as well.
-
-
-    Copyright © 2014, 2016, 2017 Simon Forman
-
-    This file is part of Thun.
-
-    Thun is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    Thun is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with Thun.  If not see <http://www.gnu.org/licenses/>.
-
-
-§ joy()
-
-The basic joy() function is quite straightforward.  It iterates through a
-sequence of terms which are either literals (strings, numbers, sequences)
-or functions.  Literals are put onto the stack and functions are
-executed.
-
-Every Joy function is an unary mapping from stacks to stacks.  Even
-literals are considered to be functions that accept a stack and return a
-new stack with the literal value on top.
-
-Exports:
-
-  joy(stack, expression, dictionary, viewer=None)
-
-  run(text, stack, dictionary, viewer=None)
-
-  repl(stack=(), dictionary=())
 
 '''
 from __future__ import print_function
@@ -62,8 +35,13 @@ from .utils.pretty_print import TracePrinter
 
 
 def joy(stack, expression, dictionary, viewer=None):
-  '''
+  '''Evaluate the Joy expression on the stack.
-  Evaluate the Joy expression on the stack.
+  
+  The basic joy() function is quite straightforward.  It iterates through a
+  sequence of terms which are either literals (strings, numbers, sequences)
+  or functions.  Literals are put onto the stack and functions are
+  executed.
+
 
   :param quote stack: The stack.
   :param quote expression: The expression to evaluate.

joy/utils/stack.py

@@ -23,8 +23,8 @@ When talking about Joy we use the terms "stack", "list", "sequence",
 permits certain operations such as iterating and pushing and popping
 values from (at least) one end.
 
-We use the venerable two-tuple recursive form of sequences where the
+We use the  `cons list`_, a venerable two-tuple recursive sequence datastructure, where the
-empty tuple () is the empty stack and (head, rest) gives the recursive
+empty tuple ``()`` is the empty stack and ``(head, rest)`` gives the recursive
 form of a stack with one or more items on it::
 
     stack := () | (item, stack)
@@ -50,6 +50,9 @@ in this case "(head, tail)", and Python takes care of unpacking the
 incoming tuple and assigning values to the names.  (Note that Python
 syntax doesn't require parentheses around tuples used in expressions
 where they would be redundant.)
+
+.. _cons list: https://en.wikipedia.org/wiki/Cons#Lists
+
 '''
 
 ##We have two very simple functions to build up a stack from a Python
@@ -135,8 +138,8 @@ def pushback(quote, expression):
 
 ##  return list_to_stack(list(iter_stack(quote)), expression)
 
-  # This is slightly faster and won't break the
+  # In-lining is slightly faster (and won't break the
-  # recursion limit on long quotes.
+  # recursion limit on long quotes.)
 
 ##  temp = []
 ##  while quote: