Merge remote-tracking branch 'origin/master'

doc/source/advanced.rst

@@ -37,92 +37,11 @@ Run a Shoebot/Nodebox script:
 
     bot.run("example.bot")
 
-Command-line usage
-------------------
 
-Enter `sbot -h` to see all the available options:
-
-.. code:: text
-
-    usage: usage: sbot [options] inputfile.bot [args] [-h] [-o FILE] [-s]
-                                                      [-p SERVERPORT] [-v VARS]
-                                                      [-ns NAMESPACE] [-l]
-                                                      [-a SCRIPT_ARGS] [-r REPEAT]
-                                                      [-g GRAMMAR] [-w] [-f]
-                                                      [-t TITLE] [-c] [-dv] [-dt]
-                                                      [-V]
-                                                      script [script_args]
-
-.. code:: text
-
-    positional arguments:
-      script                Shoebot / Nodebox script to run (filename or code)
-
-    optional arguments:
-      -h, --help            show this help message and exit
-
-
-Input / Output:
-
-.. code:: text
-
-      -o FILE, --outputfile FILE
-                            run script and output to image file (accepts .png .svg
-                            .pdf and .ps extensions)
-      -s, --socketserver    run a socket server for external control (will run the
-                            script in windowed mode)
-      -p SERVERPORT, --serverport SERVERPORT
-                            set socketserver port to listen for connections
-                            (default is 7777)
-      -v VARS, --vars VARS  Initial variables, in JSON (Note: Single quotes
-                            OUTSIDE, double INSIDE) --vars='{"variable1": 1}'
-      -ns NAMESPACE, --namespace NAMESPACE
-                            Initial namespace, in JSON (Note: Single quotes
-                            OUTSIDE, double INSIDE) --namespace='{"variable1": 1}'
-      -l, --l               Simple shell - for IDE interaction
-      -a SCRIPT_ARGS, --args SCRIPT_ARGS
-                            Pass to the bot
-      script_args
-
-Bot Lifecycle:
-
-.. code:: text
-
-      -r REPEAT, --repeat REPEAT
-                            set number of iteration, multiple images will be
-                            produced
-      -g GRAMMAR, --grammar GRAMMAR
-                            Select the bot grammar 'nodebox' (default) or
-                            'drawbot' languages
-
-Window Management:
-
-.. code:: text
-
-      -w, --window          run script in a GTK window
-      -f, --fullscreen      run in fullscreen mode
-      -t TITLE, --title TITLE
-                            Set window title
-      -c, --close           Close window after running bot (use with -r for
-                            benchmarking)
-      -dv, --disable-vars   disable the variables pane when in windowed mode.
-
-Debugging / Dev flags:
-
-.. code:: text
-
-      -dt, --disable-background-thread
-                            disable running bot code in background thread.
-      -V, --verbose         Show internal shoebot error information in traceback
-
-
-.. _shell-mode:
-
-Shell mode
-----------
-
-When run with the ``-l`` option, ``sbot`` gives you a shell inside which to control the windowed script.
+Using with Django
+-----------------
 
+See the `shoebot-django <https://github.com/stuaxo/shoebot-django>`_ for an example of integrating Shoebot into a Django application.
 
 Shoebox Virtual Machine
 -----------------------
@@ -133,8 +52,3 @@ It is the easiest way to get non-GNU/Linux systems running Shoebot. Even for GNU
 
 To try this, `Download VirtualBox <https://virtualbox.org/wiki/Downloads>`_, and then get the `Shoebox appliance file <https://mega.co.nz/#!B15lxKAZ!xLqAvVzIVV6BvBmBHZhlDJGkxHLx5yhfYC_z246Fy94>`_ (1.5 GB), import it into VirtualBox through ``File > Import Appliance``, and launch your new Shoebox.
 
-
-Using with Django
------------------
-
-See the `shoebot-django <https://github.com/stuaxo/shoebot-django>`_ for an example of integrating Shoebot into a Django application.

doc/source/commands.rst

@@ -1,16 +1,18 @@
 Command reference
 =================
 
-This documentation is still missing many parts. Refer to the [Nodebox
-documentation](https://www.nodebox.net/code/index.php/Reference) for the best
+This documentation is still missing some parts. Refer to the `Nodebox
+documentation <https://www.nodebox.net/code/index.php/Reference>`_ for the best
 reference in the meantime.
 
+.. contents:: :local:
+
 Drawing shapes
 --------------
 
 .. py:function:: rect(x, y, width, height, roundness=0, draw=True, fill=None)
 
-    Draw a rectangle on the canvas.
+    Draw a rectangle.
 
     :param x: top left x-coordinate
     :param y: top left y-coordinate
@@ -31,7 +33,7 @@ Drawing shapes
 
 .. py:function:: ellipse(x, y, width, height, draw=True)
 
-    Draw an ellipse on the canvas. Same as `oval()`.
+    Draw an ellipse. Same as ``oval()``.
 
     :param x: top left x-coordinate
     :param y: top left y-coordinate
@@ -47,7 +49,7 @@ Drawing shapes
 
 .. py:function:: arrow(x, y, width, type=NORMAL, draw=True)
 
-    Draw an arrow on the canvas.
+    Draw an arrow.
 
     :param x: arrow tip x-coordinate
     :param y: arrow tip y-coordinate
@@ -64,7 +66,7 @@ Drawing shapes
 
 .. py:function:: star(startx, starty, points=20, outer=100, inner=50, draw=True)
 
-    Draw a star-like polygon on the canvas.
+    Draw a star-like polygon.
 
     :param startx: center x-coordinate
     :param starty: center y-coordinate
@@ -451,7 +453,19 @@ Text
 Dynamic variables
 -----------------
 
-.. py:function:: var(name, type, default=None, min=0, max=255, value=None)
+.. py:function:: var(name, type, default=None, min=0, max=255, value=None, step=None, steps=256.0)
+
+  Create a :doc:`live variable <live>`.
+
+  :param name: Variable name
+  :param type: Variable type
+  :type type: NUMBER, TEXT, BOOLEAN or BUTTON
+  :param default: Default value
+  :param min: Minimum value (NUMBER only)
+  :param max: Maximum value (NUMBER only)
+  :param value: Initial value (if not defined, use ``default``)
+  :param step: Step length for the variables GUI (use this or ``steps``, not both)
+  :param steps: Number of steps in the variables GUI (use this or ``step``, not both)
 
 Utility functions
 -----------------
@@ -462,16 +476,16 @@ Utility functions
 
 .. py:function:: files(path="*")
 
-    You can use wildcards to specify which files to pick, e.g.
-    ``>>> f = files('*.gif')``
+    You can use wildcards to specify which files to pick, e.g. ``f = files('*.gif')``
 
-    :param path: wildcard to use in file list.
+    :param path: wildcard to use in file list
 
 .. py:function:: autotext(sourceFile)
 
-generates mock philosophy based on a context-free grammar
-
+   Generates mock philosophy based on a context-free grammar.
 
+   :param sourcefile: file path to use as source
+   :rtype: the generated text
 
 .. py:function:: snapshot(filename=None, surface=None, defer=None, autonumber=False)
 

doc/source/contributing.rst

@@ -0,0 +1,56 @@
+============
+Contributing
+============
+
+Development tasks
+=================
+
+Help port examples
+------------------
+
+There are many examples in the `nodebox-pyobjc <https://github.com/karstenw/nodebox-pyobjc/tree/master/examples>`_ port that aren't yet ported to Shoebot. They should work mostly without modifications -- we need help testing them. 
+
+Try them out and post any issues you find on our `issue tracker <https://github.com/shoebot/shoebot/issues/>`_.
+
+Help port libraries
+-------------------
+
+We're missing these Nodebox libraries; can you help us port them to Shoebot?
+
+- Knowledge
+
+  * `WordNet <https://www.nodebox.net/code/index.php/WordNet>`_ -- the bundled wordnet should be downloadable separately
+  * `Keywords <https://www.nodebox.net/code/index.php/Keywords>`_
+  * `Linguistics <https://www.nodebox.net/code/index.php/Linguistics>`_
+
+- Bitmap
+
+  * `Core Image <https://www.nodebox.net/code/index.php/Core_Image>`_ -- would need to be ported to PIL
+  * `iSight <https://www.nodebox.net/code/index.php/iSight>`_ -- deal with generic webcams using Pygame (`howto <https://stackoverflow.com/a/9712824/122400>`_)
+  * `Quicktime <https://www.nodebox.net/code/index.php/Quicktime>`_ -- use a Python video lib
+
+- Systems
+
+  * `Ants <https://www.nodebox.net/code/index.php/Ants>`_
+  * `Noise <https://www.nodebox.net/code/index.php/Noise>`_
+
+- Design
+
+  * `Grid <https://www.nodebox.net/code/index.php/Grid>`_
+
+- Typography
+
+  * `Pixie <https://www.nodebox.net/code/index.php/Pixie>`_
+  * `Fatpath <https://www.nodebox.net/code/index.php/Fatpath>`_
+
+- Tangible
+
+  * `WiiNode <https://www.nodebox.net/code/index.php/WiiNode>`_
+  * `OSC <https://www.nodebox.net/code/index.php/OSC>`_
+
+- Other
+
+  * `Flowerewolf <https://github.com/karstenw/Library/tree/master/flowerewolf>`_
+  * `twyg <https://github.com/karstenw/Library/tree/master/twyg>`_
+
+

doc/source/getstarted.rst

@@ -5,18 +5,27 @@ Getting Started
 Running an example script
 -------------------------
 
-To get started, clone the Shoebot repository and head over to the `examples/` directory. Once you're there, try running:
+For your first time with Shoebot, try out the included code editor by running
 
 .. code:: bash
 
-    sbot grid/balls.bot
+    shoebot
 
-If everything went well with your installation, a window should open with an image.
+Open one of the example scripts and Run it through the `Run -> Run script` menu option or the ``Ctrl-R`` keyboard shortcut.
 
-Shoebot reads scripts written in the Nodebox language and translates them into images or animations.
+A window should open with an image.  Shoebot reads scripts written in the Nodebox language and translates them into images or animations.
 
 You can right click anywhere on the image window to view the output in full screen or export it as an image or vector file.
 
+Using the console runner
+------------------------
+
+If you prefer using your own text editor to edit files and just want something to run the scripts, the `sbot` command is what you want. Head over to the `examples/` directory and try running:
+
+.. code:: bash
+
+    sbot grid/balls.bot
+
 Headless operation
 ------------------
 
@@ -26,10 +35,6 @@ There is also a mode where the result is directly rendered into an image or vect
 
     sbot grid/balls.bot -o balls.png
 
-This will create the ``balls.png`` image file. You can also create SVG, PDF and PostScript (``.ps``) files.
-
-For a list of extra options, there's always ``--help`` or ``-h``.
-
-.. code:: bash
+This will skip the window view and create the ``balls.png`` image file. You can also create SVG, PDF and PostScript (``.ps``) files.
 
-    sbot --help
+For a list of extra options, see the :doc:`cli_flags` section.

doc/source/index.rst

@@ -1,27 +1,29 @@
 Shoebot documentation
 =====================
 
-* `Main site <https://shoebot.github.io>`
-* `GitHub repository <https://github.com/shoebot/shoebot>`
-* `Issue tracker <https://github.com/shoebot/shoebot/issues>`
+* `Main site <https://shoebot.github.io>`_
+* `GitHub repository <https://github.com/shoebot/shoebot>`_
+* `Issue tracker <https://github.com/shoebot/shoebot/issues>`_
 
-Contents:
+----
 
 .. toctree::
    :maxdepth: 2
 
    intro
    install
    getstarted
-   commands
-   advanced
-   interfacing
+   tutorial
+   live
    libraries
-   extensions
    examples
+   advanced
+   extensions
    troubleshooting
-   developing
+   commands
    cli_flags
+   contributing
+   developing
 
 
 .. We won't be needing these for now