From 2887132aeb8b428726cbc72f8ece4330002696ed Mon Sep 17 00:00:00 2001 From: Simon Forman Date: Wed, 25 Apr 2018 13:35:03 -0700 Subject: [PATCH] Editing Sphinx docs. A lot more still to do but it's coming along. --- docs/sphinx_docs/index.rst | 53 ++++++++++++++++++++++++++++++++++-- docs/sphinx_docs/joy.rst | 4 +++ docs/sphinx_docs/lib.rst | 12 ++++---- docs/sphinx_docs/library.rst | 6 +++- docs/sphinx_docs/parser.rst | 11 ++++++++ docs/sphinx_docs/pretty.rst | 4 +++ docs/sphinx_docs/stack.rst | 4 +++ 7 files changed, 84 insertions(+), 10 deletions(-) diff --git a/docs/sphinx_docs/index.rst b/docs/sphinx_docs/index.rst index b605b1e..d5453ea 100644 --- a/docs/sphinx_docs/index.rst +++ b/docs/sphinx_docs/index.rst @@ -8,7 +8,7 @@ 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 +`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 @@ -16,11 +16,19 @@ 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". +I hope that this package is useful in the sense that it provides an +additional joy interpreter (the binary in the archive from La Trobe seems +to run just fine on my modern Linux machine!) But I also hope that you +can read and understand the Python code and play with the implementation +itself. + +.. _Joy: https://en.wikipedia.org/wiki/Joy_(programming_language) + Quick Start -------------------------------------------------- -Install from PyPI in the usual way:: +Install from `PyPI`_ in the usual way:: $ pip install Thun @@ -28,11 +36,50 @@ To start the REPL:: $ python -m joy +.. _PyPI: https://pypi.org/project/Thun/ +Project Hosted on `OSDN`_ +------------------------- + +* `Source Repository`_ (Mercurial) +* `Bug tracker`_ +* `Forums`_ +* `Mailing list`_ + +.. _Bug tracker: https://osdn.net/projects/joypy/ticket/ +.. _Forums: https://osdn.net/projects/joypy/forums/ +.. _Mailing list: https://osdn.net/projects/joypy/lists/ +.. _OSDN: https://osdn.net/projects/joypy/ +.. _Source Repository: https://osdn.net/projects/joypy/scm/hg/Joypy/tree/tip/ + + +Information on the Joy language +------------------------------- + +See `the Wikipedia article`_ and `Kevin Albrecht's mirror of Manfred von Thun's original website for the Joy Programming Language`_ for more information on the Joy language. + +The best source (no pun intended) for learning about Joy is the +information made available at the website of La Trobe University (see the +mirror link above) which contains source code for the +original C interpreter, Joy language source code for various functions, +and a great deal of fascinating material mostly written by Von Thun on +Joy and its deeper facets as well as how to program in it and several +interesting aspects. It's quite a treasure trove. + +.. _the Wikipedia article: https://en.wikipedia.org/wiki/Joy_(programming_language) + +.. _Kevin Albrecht's mirror of Manfred von Thun's original website for the Joy Programming Language: http://www.kevinalbrecht.com/code/joy-mirror/index.html + + +Documentation on Thun Dialect +----------------------------- + +Thun is implemented in Python. The following is specific information for this dialect of Joy. +There are also some Jupyter notebooks. + .. toctree:: :maxdepth: 2 - :caption: Contents: joy stack diff --git a/docs/sphinx_docs/joy.rst b/docs/sphinx_docs/joy.rst index 3f32be9..ad7618a 100644 --- a/docs/sphinx_docs/joy.rst +++ b/docs/sphinx_docs/joy.rst @@ -3,6 +3,10 @@ Joy Interpreter =============== +``joy.joy`` +--------------- + + .. automodule:: joy.joy :members: diff --git a/docs/sphinx_docs/lib.rst b/docs/sphinx_docs/lib.rst index fe7bbb4..b765192 100644 --- a/docs/sphinx_docs/lib.rst +++ b/docs/sphinx_docs/lib.rst @@ -1,6 +1,6 @@ -Examples (and some documentation) for the Words in the Library -============================================================== +Functions Grouped by, er, Function with Examples +------------------------------------------------ .. code:: ipython2 @@ -11,7 +11,7 @@ Stack Chatter This is what I like to call the functions that just rearrange things on the stack. (One thing I want to mention is that during a hypothetical -compilation phase these "stack chatter" words effectively disappear, +compilation phase these "stack chatter" words effectively disappear because we can map the logical stack locations to registers that remain static for the duration of the computation. This remains to be done but it's "off the shelf" technology.) @@ -26,7 +26,7 @@ it's "off the shelf" technology.) .. parsed-literal:: - + (nothing) ``dup`` ``dupd`` @@ -682,8 +682,8 @@ Math words -23 5 -pow -~~~ +``pow`` +~~~~~~~ .. code:: ipython2 diff --git a/docs/sphinx_docs/library.rst b/docs/sphinx_docs/library.rst index 886836a..7e9995f 100644 --- a/docs/sphinx_docs/library.rst +++ b/docs/sphinx_docs/library.rst @@ -3,7 +3,11 @@ Function Reference ====================================== -.. automodule:: joy.pribrary +``joy.library`` +---------------------- + + +.. automodule:: joy.library :members: diff --git a/docs/sphinx_docs/parser.rst b/docs/sphinx_docs/parser.rst index 98105e6..2306582 100644 --- a/docs/sphinx_docs/parser.rst +++ b/docs/sphinx_docs/parser.rst @@ -2,8 +2,19 @@ Parsing Text into Joy Expressions ================================= +TODO: example... + + +``joy.parser`` +--------------- + .. automodule:: joy.parser :members: +Parser Internals +---------------- + +TODO: Document things like the regular expressions used for tokenizing, and the re.Scanner, etc... + diff --git a/docs/sphinx_docs/pretty.rst b/docs/sphinx_docs/pretty.rst index f499a1e..866588c 100644 --- a/docs/sphinx_docs/pretty.rst +++ b/docs/sphinx_docs/pretty.rst @@ -3,6 +3,10 @@ Tracing Joy Execution ===================== +``joy.utils.pretty_print`` +-------------------------- + + .. automodule:: joy.utils.pretty_print :members: diff --git a/docs/sphinx_docs/stack.rst b/docs/sphinx_docs/stack.rst index b9429e7..a4af099 100644 --- a/docs/sphinx_docs/stack.rst +++ b/docs/sphinx_docs/stack.rst @@ -3,6 +3,10 @@ Stack or Quote or Sequence or List... ===================================== +``joy.utils.stack`` +---------------------- + + .. automodule:: joy.utils.stack :members: