[Yt-svn] commit/yt-doc: 6 new changesets
Bitbucket
commits-noreply at bitbucket.org
Fri Sep 2 01:56:55 PDT 2011
6 new changesets in yt-doc:
http://bitbucket.org/yt_analysis/yt-doc/changeset/2d29d0a5c04f/
changeset: 2d29d0a5c04f
user: chummels
date: 2011-09-02 09:22:36
summary: Added command-line function descriptions for all command-line tools.
affected #: 2 files (7.6 KB)
--- a/source/askingforhelp.rst Thu Sep 01 07:18:25 2011 -0400
+++ b/source/askingforhelp.rst Fri Sep 02 00:22:36 2011 -0700
@@ -80,6 +80,8 @@
patches to the source and the plugin file, if you are utilizing something
defined in that file.
+.. _reporting-a-bug:
+
How To Report A Bug
-------------------
--- a/source/interacting_with_yt.rst Thu Sep 01 07:18:25 2011 -0400
+++ b/source/interacting_with_yt.rst Fri Sep 02 00:22:36 2011 -0700
@@ -43,7 +43,7 @@
You will have to reference the datasets you want to analyze with either
relative or absolute paths, but when you have completed your work, you can use
the command (see :ref:`command-line`) ``hubsubmit`` to (if necessary) create a
-repository and submit to the `Hub <http://hub.yt-project.org/>`_.
+repository and submit to the `yt Hub <http://hub.yt-project.org/>`_.
.. _interactive-prompt:
@@ -98,9 +98,202 @@
.. _command-line:
-Command-line Utility
+Command-line Functions
--------------------
+The developers of yt realize that there is a lot more to analyzing code
+than just making pretty pictures. That is why we included several easy-to-call
+functions that could be executed from a command-line prompt for sharing code
+and images with others, using our gui Reason, manipulating your data
+google-maps style, updating yt's codebase and more. To get a quick list of
+what is available, just type:
+
+.. code-block:: bash
+
+ yt
+
+or
+
+.. code-block:: bash
+
+ yt -h
+
+This yields all of the subcommands. Let's go through them all.
+
+.. code-block:: bash
+
+ bootstrap_dev Bootstrap a yt development environment
+ bugreport Report a bug in yt
+ halos Run HaloProfiler on one dataset
+ help (?, h) give detailed help on a specific sub-command
+ hop Run HOP on one or more datasets
+ hubsubmit Submit a mercurial repository to the yt Hub (http://h...
+ instinfo Get some information about the yt installation
+ load Load a single dataset into an IPython instance
+ mapserver Serve a plot in a GMaps-style interface
+ pastebin Post a script to an anonymous pastebin
+ pastebin_grab Print an online pastebin to STDOUT for local use. Pas...
+ pasteboard Place a file into your pasteboard.
+ pasteboard_grab Download from your or another user's pasteboard
+ plot Create a set of images
+ rpdb Connect to a currently running (on localhost) rpd ses...
+ serve Run the Web GUI Reason
+ stats Print stats and maximum density for one or more datasets
+ update Update the yt installation to the most recent version
+ upload_image Upload an image to imgur.com. Must be PNG.
+
+bootstrap_dev
++++++++++++++
+
+After you have installed yt and you want to do some development, there may
+be a few more steps to complete. This function automates building a
+development environment for you by setting up your hg preferences correctly,
+creating/linking to a bitbucket account for hosting and sharing your code,
+and setting up a pasteboard for your code snippets. A full description of
+how this works can be found in :ref:`bootstrap-dev:`.
+
+bugreport
++++++++++
+
+Encountering a bug in your own code can be a big hassle, but it can be
+exponentially worse to find it in someone else's. That's why we tried to
+make it as easy as possible for users to report bugs they find in yt.
+After you go through the necessary channels to make sure you're not just
+making a mistake (see :ref:`asking-for-help:`), you can submit bug
+reports using this nice utility.
+
+halos
++++++
+
+You can easily run the HaloProfiler utility on a single dataset, in order
+to analyze and visualize multiple halos in a simulation simultaneously and
+homogeneously. For more information about the HaloProfiler see
+:ref:`halo_profiling:`; for its command line flags, use the help command
+with the halos keyword.
+
+help
+++++
+
+Help behaves as you expect that it might. You can use it with any other
+command-line option to find out more details or if it has any flags.
+
+hop
++++
+
+This lets you run the HOP algorithm as a halo-finder on one or more
+datasets. It nominally reproduces the behavior of enzohop from the
+enzo suite. There are several flags you can use in order to specify
+your threshold, input names, output names, and whether you want to use
+dark matter or all particles. To view these flags run hop with the
+help command.
+
+hubsubmit
++++++++++
+
+We in the yt camp believe firmly in the ideals of open-source coding. To
+further those ends, we have made a location for people to share their
+nifty and useful codes with other scientists who might be able to use
+them: the `yt hub <http://hub.yt-project.org/>`_. Did you make a cool
+code for generating a movie from your simulation outputs? Submit it to
+the hub. Did you create a perl script that automates something and saves
+you some time while on a supercomputer. Submit it to the hub. And
+using the hubsubmit command, you can do this really easily. If you
+create a mercurial repository for the code you want to submit, just
+run the hubsubmit command from within its directory structure, and we'll
+take care of the rest, by putting it on bitbucket and finally submitting
+it to the hub to share with the rest of the yt community. Check out
+what people have already put up on the
+`yt hub <http://hub.yt-project.org/>`_, and see :ref:`share-your-scripts:`
+for more details about sharing your work on the hub.
+
+instinfo
+++++++++
+
+This gives very similar behavior to the update command, in that it
+will automatically update your yt version to the latest in whichever
+repository you're in (stable, development, etc.). It can also provide
+you with the hash of the version you're using.
+
+load
+++++
+
+This will start the iyt interactive environment with your specified
+dataset already loaded. See :ref:`interactive-prompt:` for more details.
+
+mapserver
++++++++++
+
+Ever wanted to interact with your data using the
+`google maps <http://maps.google.com/>`_ interace? Now you can by using the
+yt mapserver. See :ref:`mapserver:` for more details.
+
+pastebin and pastebin_grab
+++++++++++++++++++++++++++
+
+The `pastebin <http://paste.yt-project.org/>`_ is an online location where
+you can anonymously post code snippets and error messages to share with
+other users in a quick, informal way. It is often useful for debugging
+code or co-developing. By running the ``pastebin`` subcommand with a
+text file, you send the contents of that file to an anonymous pastebin;
+running the ``pastebin_grab`` subcommand with a pastebin number
+(e.g. 1768), it will grab the contents of that pastebin and send it to
+STDOUT for local use. For more details see the :ref:`pastebin`: section.
+
+pasteboard and pasteboard_grab
+++++++++++++++++++++++++++++++
+
+The pasteboard is very similar to the pastebin, except that it is not
+anonymous. It is a place you can put more polished code that you'd like
+to share with others. It might be code that is a step down from what you
+might share on the `yt hub <http://hub.yt-project.org/>`_. Of course,
+you will only have a pasteboard if you've created a development environment
+using the bootstrap-dev subcommand.
+
+plot
+++++
+
+This command generates one or many simple plots for a single dataset.
+By specifying the axis, center, width, etc. (run: yt help plot for
+details), you can create slices and projections easily at the
+command-line.
+
+rpdb
+++++
+
+Connect to a currently running (on localhost) rpd session.
+
+serve
++++++
+
+The ``serve`` subcommand initiates the Web GUI Reason. See :ref:`reason:`.
+
+stats
++++++
+
+This subcommand provides you with some basic statistics on a given dataset.
+It provides you with the number of grids and cells in each level, the time
+of the dataset, the resolution, and the maximum density in a variety of units.
+It is tantamount to performing the print_stats() inside of yt.
+
+update
+++++++
+
+This subcommand updates the yt installation to the most recent version for
+your repository (e.g. stable, 2.0, development, etc.). See
+:ref:`automated-update:` for more details.
+
+upload_image
+++++++++++++
+
+Images are often worth a thousand words, so when you're trying to
+share a piece of code that generates an image, or you're trying to
+debug image-generation scripts, it can be useful to send your
+co-authors a link to the image. This subcommand makes such sharing
+a breeze. By specifying the image to share, ``upload_image`` automatically
+uploads it anonymously to the website `imgur.com <http://imgur.com/>`_ and
+provides you with a link to share with your collaborators. Note that the
+image *must* be in the PNG format in order to use this function.
+
.. _reason:
The GUI Reason
http://bitbucket.org/yt_analysis/yt-doc/changeset/3f91a5133489/
changeset: 3f91a5133489
user: chummels
date: 2011-09-02 09:43:22
summary: Updating debug page for command line pastebin and pastebin_grab wrapper functions.
affected #: 1 file (62 bytes)
--- a/source/advanced/debugdrive.rst Fri Sep 02 00:22:36 2011 -0700
+++ b/source/advanced/debugdrive.rst Fri Sep 02 00:43:22 2011 -0700
@@ -26,22 +26,23 @@
A pastebin is a website where you can easily copy source code and error
messages to share with yt developers or your collaborators. At
http://paste.yt-project.org/ a pastebin is available for placing scripts. With
-``yt`` the script ``yt_lodgeit.py`` is distributed, which allows for
-commandline uploading and downloading of pasted snippets. To upload script you
+``yt`` the script ``yt_lodgeit.py`` is distributed and wrapped with
+the ``pastebin`` and ``pastebin_grab`` commands, which allow for commandline
+uploading and downloading of pasted snippets. To upload a script you
would supply it to the command:
.. code-block:: bash
- $ yt_lodgeit.py some_script.py
+ $ yt pastebin some_script.py
The URL will be returned. If you'd like it to be marked 'private' and not show
up in the list of pasted snippets, supply the argument ``--private``. All
snippets are given either numbers or hashes. To download a pasted snippet, you
-would use the ``--download`` option:
+would use the ``pastebin_grab`` option:
.. code-block:: bash
- $ yt_lodgeit.py --download=216
+ $ yt pastebin_grab 1768
The snippet will be output to the window, so output redirection can be used to
store it in a file.
http://bitbucket.org/yt_analysis/yt-doc/changeset/fc1df23232aa/
changeset: fc1df23232aa
user: chummels
date: 2011-09-02 10:09:01
summary: Updated asking for help section to make more linear for the directions one should take to get problems solved.
affected #: 1 file (1.2 KB)
--- a/source/askingforhelp.rst Fri Sep 02 00:43:22 2011 -0700
+++ b/source/askingforhelp.rst Fri Sep 02 01:09:01 2011 -0700
@@ -8,19 +8,28 @@
mailing list. If something doesn't work for you, it's in everyone's best
interests to make sure that it gets fixed.
+.. _search-the-documentation:
+
+Search the Documentation
+-------------
+
+The first thing that you want to do if you encounter an issue with yt is to
+do a cursory check of the documentation. This doesn't mean you have to read
+all of the docs top-to-bottom, but you should at least run a search to see
+if relevant topics have been answered in the docs. Click on the search field
+to the right of this window and enter your text. Another good place to look
+for answers in the documentation is our :ref:`faq` page.
+
.. _mailing-list:
-The Mailing List
+Search/Ask the Mailing List
----------------
-The mailing list should be your first stop, every time and always. If you are
-having a problem, it might be something other people have struggled with and
-fixed on their own, or it might be a bug -- in which case it has to be brought
-to the attention of the developers!
-
-You can search the entire yt website, including the mailing lists, by putting
-your query either here or in the search bar on the right. There is
-also a :ref:`FAQ` for some of the most common problems that can come up.
+OK, so there was no obvious solution to your problem in the documentation.
+It is possible that someone else experienced the problem before you did, and
+wrote to the mailing list about it. You can easily check the mailing list
+archive with the other search field to the right of this window (or you can
+use the search field below).
.. raw:: html
@@ -34,7 +43,8 @@
</form><script type="text/javascript" src="http://www.google.com/cse/brand?form=cse-search-box&lang=en"></script>
-There are two mailing lists,
+If you didn't find any hint of a solution in the archive, then feel free to
+write to the mailing list regarding your problems. There are two mailing lists,
`yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_ and
`yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_. The
first should be used for asking for help, suggesting features and so on, and
@@ -47,7 +57,7 @@
#. What it is that went wrong, and how you knew it went wrong.
#. A traceback if appropriate -- see :ref:`error-reporting` for some help with
that.
-#. If possible, the smallest number of steps that can reproduce the problem.
+#. If possible, the smallest number of steps that can reproduce the problem. If you're demonstrating the bug with code, you may find the :ref:`pastebin` useful.
#. Which version of the code you are using.
When you email the list, providing this information can help the developers
@@ -55,6 +65,33 @@
problems they have seen in the past. Without this context, it can be very
difficult to help out!
+.. _irc:
+
+IRC
+---
+
+If you want a more interactive experience, you could try jumping into our IRC
+channel to get your questions answered in a chatroom style environment. You
+don't even need to have any special IRC client in order to join. We are the
+#yt channel on irc.freenode.net, but you can also connect using your web
+browser by going to http://yt-project.org/irc.html . There are usually 2-8 members of the user base and development team online, so you'll probably get your
+answers quickly.
+
+.. _reporting-a-bug:
+
+How To Report A Bug
+-------------------
+
+If you have gone through all of the above steps, and you're still encountering
+problems, then you have found a bug. The first step, when reporting a bug,
+is to identify the smallest piece of code that reproduces the bug.
+To submit a bug report, you can either directly create one through the
+BitBucket `web interface <http://hg.yt-project.org/yt/issues/new>`_,
+or you can use the command line ``yt bugreport`` to interactively create one.
+Alternatively, email the ``yt-users`` mailing list and we will construct a new
+ticket in your stead.
+
+
Installation Issues
-------------------
@@ -79,17 +116,3 @@
described in :ref:`plugin-file`) then it may be necessary to supply both your
patches to the source and the plugin file, if you are utilizing something
defined in that file.
-
-.. _reporting-a-bug:
-
-How To Report A Bug
--------------------
-
-The first step, when reporting a bug, is to identify the smallest piece of code
-that reproduces the bug.
-
-To submit a bug report, you can either directly create one through the
-BitBucket `web interface <http://hg.yt-project.org/yt/issues/new>`_,
-or you can use the command line ``yt bugreport`` to interactively create one.
-Alternatively, email the ``yt-users`` mailing list and we will construct a new
-ticket in your stead.
http://bitbucket.org/yt_analysis/yt-doc/changeset/80d687142d7a/
changeset: 80d687142d7a
user: chummels
date: 2011-09-02 10:13:03
summary: Adding reference to upload_image command line option in section on "how to ask for help".
affected #: 2 files (134 bytes)
--- a/source/askingforhelp.rst Fri Sep 02 01:09:01 2011 -0700
+++ b/source/askingforhelp.rst Fri Sep 02 01:13:03 2011 -0700
@@ -57,7 +57,7 @@
#. What it is that went wrong, and how you knew it went wrong.
#. A traceback if appropriate -- see :ref:`error-reporting` for some help with
that.
-#. If possible, the smallest number of steps that can reproduce the problem. If you're demonstrating the bug with code, you may find the :ref:`pastebin` useful.
+#. If possible, the smallest number of steps that can reproduce the problem. If you're demonstrating the bug with code, you may find the :ref:`pastebin` useful.If you've got an image output that demonstrates your problem, you may find the :ref:`upload-image` function useful.
#. Which version of the code you are using.
When you email the list, providing this information can help the developers
--- a/source/interacting_with_yt.rst Fri Sep 02 01:09:01 2011 -0700
+++ b/source/interacting_with_yt.rst Fri Sep 02 01:13:03 2011 -0700
@@ -282,6 +282,8 @@
your repository (e.g. stable, 2.0, development, etc.). See
:ref:`automated-update:` for more details.
+.. _upload-image:
+
upload_image
++++++++++++
http://bitbucket.org/yt_analysis/yt-doc/changeset/9252e8a15077/
changeset: 9252e8a15077
user: chummels
date: 2011-09-02 10:18:36
summary: Just adding a line to take the edge-off on the front docs page.
affected #: 1 file (172 bytes)
--- a/source/index.rst Fri Sep 02 01:13:03 2011 -0700
+++ b/source/index.rst Fri Sep 02 01:18:36 2011 -0700
@@ -19,11 +19,10 @@
If you use ``yt`` in a paper, you are highly encouraged to submit the
repository containing the scripts you used to analyze and visualize your data
-to the `yt Hub <http://yt-project.org/>`_, and we ask that you consider citing
+to the `yt Hub <http://hub.yt-project.org/>`_, and we ask that you consider citing
our `method paper <http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, as
-well. We encourage you to explore the source code and even consider
-:ref:`contributing <contributing-code>` your enhancements and
-scripts.
+well. If you are looking to use ``yt``, then check out the `yt Hub <http://hub.yt-project.org/>`_ for ideas of how other people used ``yt`` to generate worthwhile analysis. We encourage you to explore the source code and even consider
+:ref:`contributing <contributing-code>` your enhancements and scripts.
For more information, please visit `our homepage <http://yt-project.org/>`_
and for help, please see :ref:`asking-for-help`.
http://bitbucket.org/yt_analysis/yt-doc/changeset/1af6e5ff938e/
changeset: 1af6e5ff938e
user: chummels
date: 2011-09-02 10:56:09
summary: Correcting some bugs in inter-page references.
affected #: 2 files (208 bytes)
--- a/source/getting_involved.rst Fri Sep 02 01:18:36 2011 -0700
+++ b/source/getting_involved.rst Fri Sep 02 01:56:09 2011 -0700
@@ -37,7 +37,7 @@
If you have an idea about something, suggest it! We not only welcome
participation, we encourage it.
-.. share-your-scripts:
+.. share-your-scripts
Share Your Scripts
------------------
--- a/source/interacting_with_yt.rst Fri Sep 02 01:18:36 2011 -0700
+++ b/source/interacting_with_yt.rst Fri Sep 02 01:56:09 2011 -0700
@@ -104,21 +104,21 @@
The developers of yt realize that there is a lot more to analyzing code
than just making pretty pictures. That is why we included several easy-to-call
functions that could be executed from a command-line prompt for sharing code
-and images with others, using our gui Reason, manipulating your data
+and images with others, using our GUI Reason, manipulating your data
google-maps style, updating yt's codebase and more. To get a quick list of
what is available, just type:
.. code-block:: bash
- yt
+ yt -h
-or
+This yields all of the subcommands. To execute any subcommand, simply run:
.. code-block:: bash
- yt -h
+ yt <subcommand>
-This yields all of the subcommands. Let's go through them all.
+Let's go through each subcommand.
.. code-block:: bash
@@ -150,7 +150,7 @@
development environment for you by setting up your hg preferences correctly,
creating/linking to a bitbucket account for hosting and sharing your code,
and setting up a pasteboard for your code snippets. A full description of
-how this works can be found in :ref:`bootstrap-dev:`.
+how this works can be found in :ref:`bootstrap-dev`.
bugreport
+++++++++
@@ -159,7 +159,7 @@
exponentially worse to find it in someone else's. That's why we tried to
make it as easy as possible for users to report bugs they find in yt.
After you go through the necessary channels to make sure you're not just
-making a mistake (see :ref:`asking-for-help:`), you can submit bug
+making a mistake (see :ref:`asking-for-help`), you can submit bug
reports using this nice utility.
halos
@@ -168,14 +168,18 @@
You can easily run the HaloProfiler utility on a single dataset, in order
to analyze and visualize multiple halos in a simulation simultaneously and
homogeneously. For more information about the HaloProfiler see
-:ref:`halo_profiling:`; for its command line flags, use the help command
+:ref:`halo_profiling`; for its command line flags, use the help command
with the halos keyword.
help
++++
Help behaves as you expect that it might. You can use it with any other
-command-line option to find out more details or if it has any flags.
+command-line option to find out more details or if it has any flags:
+
+.. code-block:: bash
+
+ yt help <subcommand>
hop
+++
@@ -184,8 +188,8 @@
datasets. It nominally reproduces the behavior of enzohop from the
enzo suite. There are several flags you can use in order to specify
your threshold, input names, output names, and whether you want to use
-dark matter or all particles. To view these flags run hop with the
-help command.
+dark matter or all particles. To view these flags run help with the
+hop subcommand.
hubsubmit
+++++++++
@@ -203,7 +207,7 @@
take care of the rest, by putting it on bitbucket and finally submitting
it to the hub to share with the rest of the yt community. Check out
what people have already put up on the
-`yt hub <http://hub.yt-project.org/>`_, and see :ref:`share-your-scripts:`
+`yt hub <http://hub.yt-project.org/>`_, and see :ref:`share-your-scripts`
for more details about sharing your work on the hub.
instinfo
@@ -218,14 +222,14 @@
++++
This will start the iyt interactive environment with your specified
-dataset already loaded. See :ref:`interactive-prompt:` for more details.
+dataset already loaded. See :ref:`interactive-prompt` for more details.
mapserver
+++++++++
Ever wanted to interact with your data using the
-`google maps <http://maps.google.com/>`_ interace? Now you can by using the
-yt mapserver. See :ref:`mapserver:` for more details.
+`google maps <http://maps.google.com/>`_ interface? Now you can by using the
+yt mapserver. See :ref:`mapserver` for more details.
pastebin and pastebin_grab
++++++++++++++++++++++++++
@@ -235,9 +239,18 @@
other users in a quick, informal way. It is often useful for debugging
code or co-developing. By running the ``pastebin`` subcommand with a
text file, you send the contents of that file to an anonymous pastebin;
-running the ``pastebin_grab`` subcommand with a pastebin number
+
+.. code-block:: bash
+
+ yt pastebin my_script.py
+
+By running the ``pastebin_grab`` subcommand with a pastebin number
(e.g. 1768), it will grab the contents of that pastebin and send it to
-STDOUT for local use. For more details see the :ref:`pastebin`: section.
+STDOUT for local use. For more details see the :ref:`pastebin` section.
+
+.. code-block:: bash
+
+ yt pastebin_grab 1768
pasteboard and pasteboard_grab
++++++++++++++++++++++++++++++
@@ -253,7 +266,7 @@
++++
This command generates one or many simple plots for a single dataset.
-By specifying the axis, center, width, etc. (run: yt help plot for
+By specifying the axis, center, width, etc. (run ``yt help plot`` for
details), you can create slices and projections easily at the
command-line.
@@ -265,7 +278,7 @@
serve
+++++
-The ``serve`` subcommand initiates the Web GUI Reason. See :ref:`reason:`.
+The ``serve`` subcommand initiates the Web GUI Reason. See :ref:`reason`.
stats
+++++
@@ -273,14 +286,14 @@
This subcommand provides you with some basic statistics on a given dataset.
It provides you with the number of grids and cells in each level, the time
of the dataset, the resolution, and the maximum density in a variety of units.
-It is tantamount to performing the print_stats() inside of yt.
+It is tantamount to performing the ``print_stats()`` inside of yt.
update
++++++
This subcommand updates the yt installation to the most recent version for
your repository (e.g. stable, 2.0, development, etc.). See
-:ref:`automated-update:` for more details.
+:ref:`automated-update` for more details.
.. _upload-image:
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