[Yt-svn] commit/yt-doc: MatthewTurk: Importing first pass at Reason docs and adding faq.rst to the main index.
Bitbucket
commits-noreply at bitbucket.org
Wed Aug 31 15:07:30 PDT 2011
1 new changeset in yt-doc:
http://bitbucket.org/yt_analysis/yt-doc/changeset/7e83ca359b86/
changeset: 7e83ca359b86
user: MatthewTurk
date: 2011-09-01 00:07:22
summary: Importing first pass at Reason docs and adding faq.rst to the main index.
affected #: 7 files (863.4 KB)
--- a/source/index.rst Wed Aug 31 16:52:24 2011 -0400
+++ b/source/index.rst Wed Aug 31 18:07:22 2011 -0400
@@ -41,6 +41,7 @@
getting_involved
askingforhelp
advanced/index
+ faq
reference/index
Indices and tables
--- a/source/interacting_with_yt.rst Wed Aug 31 16:52:24 2011 -0400
+++ b/source/interacting_with_yt.rst Wed Aug 31 18:07:22 2011 -0400
@@ -29,8 +29,9 @@
the alias ``pyyt``.
#. Edit, and repeat!
-To encourage easy submission to :ref:`hub`, we suggest you place your scripts
-in an isolated subdirectory and name each one individually. For instance:
+To encourage easy submission to the `yt Hub <http://hub.yt-project.org/`_, we
+suggest you place your scripts in an isolated subdirectory and name each one
+individually. For instance:
.. code-block:: bash
@@ -105,6 +106,232 @@
The GUI Reason
--------------
+.. warning:: Current versions of Reason may not work quite as expected with
+ Firefox. They have all been tested under Chrome, and if you run
+ into any bugs with either, please `report them
+ <https://bitbucket.org/yt_analysis/yt/issues/new>`_!
+
+Demo
+++++
+
+This is where the screencast should be placed!
+
+What is Reason?
++++++++++++++++
+
+Reason is a web-based GUI for yt. It's still currently a BETA sequence, but we
+are working very hard to improve it and ensure it's productive. It's designed
+to act as a very simple web-notebook -- it's not a replacement for something
+like the much more complex IPython web notebook, or the SAGE notebook, but
+rather a means of exploring simulation data easily, safely, and without
+requiring the overhead of additional dependencies.
+
+Everything you need to run reason comes right with the yt install script -- if
+you have installed yt another way, you may need to separately obtain the ExtJS
+packages.
+
+The idea behind reason is to spawn a web server on a shared resource system,
+and connect to that web server from your desktop, tunnelling over SSH. Reason
+is not designed to be run over unencrypted wires; you should either be running
+fully locally or through an SSH tunnel. Reasonable steps have been taken to
+ensure that your connections are safe: each connection occurs only on a random
+port (which is potentially identifiable on a shared user system) and with a
+UUID prefixed into each URL (which should be difficult if not impossible to
+identify without root authority.
+
+Starting Reason
++++++++++++++++
+
+Reason can be started very easily from the command line:
+
+.. code-block:: bash
+
+ $ yt serve
+
+If you are running on your local machine, you can also execute:
+
+.. code-block:: bash
+
+ $ yt serve -o
+
+to open up a local web browser window. If you want Reason to search for
+(currently only Enzo) parameter files under your current directory, you can
+execute:
+
+.. code-block:: bash
+
+ $ yt serve -o -f
+
+yt will print out something like:
+
+.. code-block:: bash
+
+ =============================================================================
+ =============================================================================
+ Greetings, and welcome to Reason!
+ Your private token is c2dcd1dc-d40f-11e0-8f6b-bc305ba67797 .
+ DO NOT SHARE THIS TOKEN.
+
+ Please direct your browser to:
+
+ http://localhost:51707/c2dcd1dc-d40f-11e0-8f6b-bc305ba67797/
+
+ =============================================================================
+
+ If you are currently ssh'd into a remote machine, you should be able
+ to create a new SSH tunnel by typing or copy/pasting this text
+ verbatim, while waiting to see the 'ssh>' prompt after the first line.
+
+ ~C
+ -L51707:localhost:51707
+
+ and then pointing a web browser on your local machine to the above URL.
+
+ =============================================================================
+ =============================================================================
+
+If you are on a remote machine, you will need to execute the one additional
+step that yt mentions in order to be able to connect. Press ~C (that's tilde,
+then C) which should bring up a prompt that looks like ``ssh>`` . At that
+prompt, type what you are told to, which will open up a port over which you can
+tunnel to talk to the server:
+
+.. code-block:: bash
+
+ ssh>-L51707:localhost:51707
+
+Now you can open the URL printed out.
+
+What is Within Reason?
+++++++++++++++++++++++
+
+Once you start up reason, for the first time, you will see something like:
+
+.. image:: _images/rs1_welcome.png
+ :target: _images/rs1_welcome.png
+ :width: 500
+
+This is the basic layout. There are three primary components:
+
+ * (top, left) *Object List*: The list of parameter files and objects. Every
+ time you load a parameter file or create a (persistent) data object, it will
+ appear here.
+ * (top, right) *Interaction Area*: this is where the notebook and any
+ widgets will appear.
+ * (bottom) *Log Area*: The messages normally spit out to the log will be put
+ here.
+
+The main mechanism of interacting with reason is through the notebook. You can
+type commands in. When you either click the down-arrow on the right or press
+Shift-Enter, these commands will be sent and execute on the far side. This
+should be thought of more like a series of mini-scripts, rather than individual
+lines: you can send multiple lines of input, including for loops, conditionals,
+and so on, very easily. If you want to access any object, you can drag it from
+the object list, as demonstrated here, where I have drug in the parameter file
+and called ``print_stats`` on its hierarchy:
+
+.. image:: _images/rs2_printstats.png
+ :target: _images/rs2_printstats.png
+ :width: 500
+
+Any command can be executed here, and the output will appear in an output cell
+below. The output cells have two sets of arrows on them. The leftmost (blue)
+arrow will upload the contents of that cell to the yt `pastebin
+<http://paste.yt-project.org/>`_. The rightmost (green) set of double arrows
+will put the contents of that cell up top, in the execution zone -- this is
+useful if you are iterating on a command.
+
+You can also right-click on a parameter file to create slices, projections and
+to view grid information. *(There is also an experimental WebGL component that
+is currently disabled!)* If you right click on a parameter file, you can
+choose to project the dataset. Progress bars have been added, so you should be
+mapserver.png
+able to view progress as normal:
+
+.. image:: _images/rs3_proj.png
+ :target: _images/rs3_proj.png
+ :width: 500
+
+Once the projecting is done, a new tab for the plot widget should be opened.
+This will include the image, a colorbar, a metadata window, and a couple
+buttons to press:
+
+.. image:: _images/rs4_widget.png
+ :target: _images/rs4_widget.png
+ :width: 500
+
+You can ctrl-click on the image (this is broken in Firefox, but works in
+Chrome! We're working to fix it!) to re-center on a given location. The
+scroll bar at the bottom controls zooming, and you can dynamically change the
+field that is displayed. There are zoom controls as well as panning controls,
+and the option to upload the image to `imgur.com <http://imgur.com/>`_, a
+simple image sharing service on the web.
+
+There are also phase plot widgets, slice widgets, and we're working on a few
+other fun WebGL widgets.
+
+What Special Things Can Reason Do?
+++++++++++++++++++++++++++++++++++
+
+There are several special commands that Reason builds in, that make a few
+common operations easy.
+
+ * ``load_script(filename)`` will load a script from the file system and insert
+ it into the currently-active input area.
+ * ``deliver_image(filename)`` can accept a filename (PNG-only), a string of
+ binary PNG data, or a file-like object full of PNG data. This data will
+ then be delivered to the browser, in the next active cell. This is the
+ mechanism by which most image display occurs in Reason.
+
+Plot collections have been instrumented to work with Reason. This means that
+if you create a plot collection like normal, as soon as you run ``pc.save()``
+the images that are saved out will be displayed in the active cell output.
+
+Pylab has also been modified to work with Reason, and Reason imports it before
+it starts up. You can run any normal pylab command:
+
+.. code-block:: python
+
+ pylab.plot([1, 2, 3, 4, 5], [10, 210, 503, 1, 42.1])
+
+and the output should appear in the active cell.
+
+You may notice that there is a menu above the object list:
+
+.. image:: _images/rs5_menu.png
+ :width: 500
+ :target: _images/rs5_menu.png
+
+There are a number of options here:
+
+ * ``Open`` and ``Open Directory`` -- currently disabled while we implement
+ this functionality.
+ * ``Save Script`` -- Save the concatenated set of executed cells to a file on
+ the server. This script should be directly executable, including all widget
+ interactions.
+ * ``Download Script`` -- Download the concatenated set of executed cells to a
+ file on your local machine.
+ * ``Pastebin Script`` -- Upload the concatenated set of executed cells to the
+ `yt pastebin <http://paste.yt-project.org/>`.
+ * ``Help`` -- A quick little help file.
+ * ``yt Chat`` -- Open up the Web portal to IRC, for live chatting with other
+ yt users and developers.
+
+Please feel free to share with us your thoughts and experiences -- good and
+bad! -- with Reason.
+
+I Want To Add A Widget!
++++++++++++++++++++++++
+
+Adding a new widget is pretty straightforward, but you might need some guidance
+along the way. It might be a good idea to stop by the yt-dev mailing list (see
+:ref:`getting-involved`) but you can also explore how widgets are made in the
+directory ``yt/gui/reason/html/js/`` and take a look at the specific python
+code in ``yt/gui/reason/extdirect_repl.py``.
+
+But seriously, if you have the desire to play with or update or extend or
+prettify reason, we'd be really excited to work with you.
+
.. _mapserver:
Mapserver
Repository URL: https://bitbucket.org/yt_analysis/yt-doc/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
More information about the yt-svn
mailing list