[Yt-svn] commit/yt-doc: 3 new changesets
Bitbucket
commits-noreply at bitbucket.org
Fri Feb 25 21:12:53 PST 2011
3 new changesets in yt-doc:
http://bitbucket.org/yt_analysis/yt-doc/changeset/a2cfdb707493/
changeset: r24:a2cfdb707493
user: MatthewTurk
date: 2011-02-26 05:34:29
summary: Adding the how_to_develop_yt.txt file, making a few changes to it.
affected #: 1 file (5.2 KB)
--- a/source/advanced/contribution.rst Thu Feb 24 17:05:07 2011 -0700
+++ b/source/advanced/contribution.rst Fri Feb 25 23:34:29 2011 -0500
@@ -1,18 +1,169 @@
.. _contributing-code:
-Contributing Code
+How to Develop yt
=================
-We'd love your contributions to ``yt``!
+yt is a community project!
-``yt`` is designed to be accessible to contributions, of both enhancements to
-the core packages and the library of recipes and scripts for performing common
--- and not-so-common -- tasks. The ``yt`` dev community is growing, and we're
-eager to have newcomers on board.
+We are very happy to accept patches, features, and bugfixes from any member of
+the community! yt is developed using mercurial, primarily because it enables
+very easy and straightforward submission of changesets. We're eager to hear
+from you, and if you are developing yt, we encourage you to subscribe to the
+`developer mailing list
+<http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
-On the main Wiki page, `some guidelines
-<http://yt.enzotools.org/wiki/GettingInvolved>`_ have been left to help you on
-your way to adding code, contributing modules, and helping out.
+Please feel free to hack around, commit changes, and send them upstream. If
+you're new to Mercurial, these three resources are pretty great for learning
+the ins and outs:
+
+ * `http://hginit.com`_
+ * `http://hgbook.red-bean.com/read/`_
+ * `http://mercurial.selenic.com/`_
+
+Keep in touch, and happy hacking! We also provide doc/coding_styleguide.txt
+and an example of a fiducial docstring in doc/docstring_example.txt. Please
+read them before hacking on the codebase, and feel free to email any of the
+mailing lists for help with the codebase.
+
+Licensing
+--------
+
+All code in yt should be under the GPL-3 (preferred) or a compatible license.
+
+How To Get The Source Code
+--------------------------
+
+yt is hosted on BitBucket, and you can see all of the yt repositories at
+`http://hg.enzotools.org/`_. With the yt installation script you should have a
+copy of Mercurial. You can clone the repository like so:
+
+.. code-block:: bash
+
+ $ hg clone http://hg.enzotools.org/yt/
+
+You can update to any branch or revision by executing the command:
+
+.. code-block:: bash
+
+ $ hg up -C some_revision_specifier
+
+Specifying a branch name in the revspec will update to the latest revision on
+that branch. If you ran the installation script, you can tell Python to use a
+different version of the library by executing:
+
+.. code-block:: bash
+
+ $ python2.6 setup.py develop
+
+This will rebuild all C modules as well.
+
+How To Submit Changes
+---------------------
+
+You can submit changes a couple different ways, but the easiest is to use the
+"fork" mechanism on BitBucket. Just go to the "fork" page at:
+
+`http://hg.enzotools.org/yt/fork`_
+
+and you're all set, ready to go. You'll have to either clone a new copy of the
+repository or edit .hg/hgrc to point to the location of your new fork, first,
+though.
+
+When you're ready to submit them to the main repository, simply go to:
+
+`http://hg.enzotools.org/yt/fork`_
+
+Make sure you notify "yt_analysis" and put in a little description. That'll
+notify the core developers that you've got something ready to submit, and we
+will review it an (hopefully!) merge it in. If it goes well, you may end up
+with push access to the main repository.
+
+How To Read The Source Code
+---------------------------
+
+yt is organized into several sub-packages, each of which governs a different
+conceptual regime.
+
+ frontends
+ This is where interfaces to codes are created. Within each subdirectory of
+ yt/frontends/ there must exist the following files, even if empty:
+
+ * data_structures.py, where subclasses of AMRGridPatch, StaticOutput and
+ AMRHierarchy are defined.
+ * io.py, where a subclass of IOHandler is defined.
+ * misc.py, where any miscellaneous functions or classes are defined.
+ * definitions.py, where any definitions specific to the frontend are
+ defined. (i.e., header formats, etc.)
+
+ visualization
+ This is where all visualization modules are stored. This includes plot
+ collections, the volume rendering interface, and pixelization frontends.
+
+ data_objects
+ All objects that handle data, processed or unprocessed, not explicitly
+ defined as visualization are located in here. This includes the base
+ classes for data regions, covering grids, time series, and so on. This
+ also includes derived fields and derived quantities.
+
+ analysis_modules
+ This is where all mechanisms for processing data live. This includes
+ things like clump finding, halo profiling, halo finding, and so on. This
+ is something of a catchall, but it serves as a level of greater
+ abstraction that simply data selection and modification.
+
+ gui
+ This is where all GUI components go. Typically this will be some small
+ tool used for one or two things, which contains a launching mechanism on
+ the command line.
+
+ utilities
+ All broadly useful code that doesn't clearly fit in one of the other
+ categories goes here.
+
+How To Use Branching
+--------------------
+
+If you are planning on making a large change to the code base that may not be
+ready for many commits, or if you are planning on breaking some functionality
+and rewriting it, you are encouraged to create a new named branch. You can
+mark the current repository as a new named branch by executing:
+
+.. code-block:: bash
+
+ $ hg branch new_feature_name
+
+The next commit and all subsequent commits will be contained within that named
+branch. At this point, add your branch here:
+
+`http://yt.enzotools.org/wiki/ExistingBranches`_
+
+To merge changes in from another branch, you would execute:
+
+.. code-block:: bash
+
+ $ hg merge some_other_branch
+
+Note also that you can use revision specifiers instead of "some_other_branch".
+When you are ready to merge back into the main branch, execute this process:
+
+.. code-block:: bash
+
+ $ hg merge name_of_main_branch
+ $ hg commit --close-branch
+ $ hg up -C name_of_main_branch
+ $ hg merge name_of_feature_branch
+ $ hg commit
+
+When you execute the merge you may have to resolve conflicts. Once you resolve
+conflicts in a file, you can mark it as resolved by doing:
+
+.. code-block:: bash
+
+ $ hg resolve -m path/to/conflicting/file.py
+
+Please be careful when resolving conflicts in files.
+
+Once your branch has been merged in, mark it as closed on the wiki page.
Project Ideas
-------------
@@ -92,4 +243,5 @@
usage-cases, but of real-world examples of plot generation and data analysis.
If you are interested in submitting your scripts, please contact Matt Turk at
-``matthewturk at gmail.com``.
+``matthewturk at gmail.com``, or just create a repository on BitBucket and send
+over the URL!
http://bitbucket.org/yt_analysis/yt-doc/changeset/91140ef7a981/
changeset: r25:91140ef7a981
user: MatthewTurk
date: 2011-02-26 05:36:18
summary: Renaming contributing to developing
affected #: 3 files (8.9 KB)
--- a/source/advanced/contribution.rst Fri Feb 25 23:34:29 2011 -0500
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,247 +0,0 @@
-.. _contributing-code:
-
-How to Develop yt
-=================
-
-yt is a community project!
-
-We are very happy to accept patches, features, and bugfixes from any member of
-the community! yt is developed using mercurial, primarily because it enables
-very easy and straightforward submission of changesets. We're eager to hear
-from you, and if you are developing yt, we encourage you to subscribe to the
-`developer mailing list
-<http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
-
-Please feel free to hack around, commit changes, and send them upstream. If
-you're new to Mercurial, these three resources are pretty great for learning
-the ins and outs:
-
- * `http://hginit.com`_
- * `http://hgbook.red-bean.com/read/`_
- * `http://mercurial.selenic.com/`_
-
-Keep in touch, and happy hacking! We also provide doc/coding_styleguide.txt
-and an example of a fiducial docstring in doc/docstring_example.txt. Please
-read them before hacking on the codebase, and feel free to email any of the
-mailing lists for help with the codebase.
-
-Licensing
---------
-
-All code in yt should be under the GPL-3 (preferred) or a compatible license.
-
-How To Get The Source Code
---------------------------
-
-yt is hosted on BitBucket, and you can see all of the yt repositories at
-`http://hg.enzotools.org/`_. With the yt installation script you should have a
-copy of Mercurial. You can clone the repository like so:
-
-.. code-block:: bash
-
- $ hg clone http://hg.enzotools.org/yt/
-
-You can update to any branch or revision by executing the command:
-
-.. code-block:: bash
-
- $ hg up -C some_revision_specifier
-
-Specifying a branch name in the revspec will update to the latest revision on
-that branch. If you ran the installation script, you can tell Python to use a
-different version of the library by executing:
-
-.. code-block:: bash
-
- $ python2.6 setup.py develop
-
-This will rebuild all C modules as well.
-
-How To Submit Changes
----------------------
-
-You can submit changes a couple different ways, but the easiest is to use the
-"fork" mechanism on BitBucket. Just go to the "fork" page at:
-
-`http://hg.enzotools.org/yt/fork`_
-
-and you're all set, ready to go. You'll have to either clone a new copy of the
-repository or edit .hg/hgrc to point to the location of your new fork, first,
-though.
-
-When you're ready to submit them to the main repository, simply go to:
-
-`http://hg.enzotools.org/yt/fork`_
-
-Make sure you notify "yt_analysis" and put in a little description. That'll
-notify the core developers that you've got something ready to submit, and we
-will review it an (hopefully!) merge it in. If it goes well, you may end up
-with push access to the main repository.
-
-How To Read The Source Code
----------------------------
-
-yt is organized into several sub-packages, each of which governs a different
-conceptual regime.
-
- frontends
- This is where interfaces to codes are created. Within each subdirectory of
- yt/frontends/ there must exist the following files, even if empty:
-
- * data_structures.py, where subclasses of AMRGridPatch, StaticOutput and
- AMRHierarchy are defined.
- * io.py, where a subclass of IOHandler is defined.
- * misc.py, where any miscellaneous functions or classes are defined.
- * definitions.py, where any definitions specific to the frontend are
- defined. (i.e., header formats, etc.)
-
- visualization
- This is where all visualization modules are stored. This includes plot
- collections, the volume rendering interface, and pixelization frontends.
-
- data_objects
- All objects that handle data, processed or unprocessed, not explicitly
- defined as visualization are located in here. This includes the base
- classes for data regions, covering grids, time series, and so on. This
- also includes derived fields and derived quantities.
-
- analysis_modules
- This is where all mechanisms for processing data live. This includes
- things like clump finding, halo profiling, halo finding, and so on. This
- is something of a catchall, but it serves as a level of greater
- abstraction that simply data selection and modification.
-
- gui
- This is where all GUI components go. Typically this will be some small
- tool used for one or two things, which contains a launching mechanism on
- the command line.
-
- utilities
- All broadly useful code that doesn't clearly fit in one of the other
- categories goes here.
-
-How To Use Branching
---------------------
-
-If you are planning on making a large change to the code base that may not be
-ready for many commits, or if you are planning on breaking some functionality
-and rewriting it, you are encouraged to create a new named branch. You can
-mark the current repository as a new named branch by executing:
-
-.. code-block:: bash
-
- $ hg branch new_feature_name
-
-The next commit and all subsequent commits will be contained within that named
-branch. At this point, add your branch here:
-
-`http://yt.enzotools.org/wiki/ExistingBranches`_
-
-To merge changes in from another branch, you would execute:
-
-.. code-block:: bash
-
- $ hg merge some_other_branch
-
-Note also that you can use revision specifiers instead of "some_other_branch".
-When you are ready to merge back into the main branch, execute this process:
-
-.. code-block:: bash
-
- $ hg merge name_of_main_branch
- $ hg commit --close-branch
- $ hg up -C name_of_main_branch
- $ hg merge name_of_feature_branch
- $ hg commit
-
-When you execute the merge you may have to resolve conflicts. Once you resolve
-conflicts in a file, you can mark it as resolved by doing:
-
-.. code-block:: bash
-
- $ hg resolve -m path/to/conflicting/file.py
-
-Please be careful when resolving conflicts in files.
-
-Once your branch has been merged in, mark it as closed on the wiki page.
-
-Project Ideas
--------------
-
-There are lots of places in ``yt`` where new extensions could be added, or new
-functionality put in place. Here are a few.
-
-Adding Support for a New Code
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``yt`` strives to be a general-purpose analysis tool for astrophysical data.
-To that end, we'd like to short up our support for codes besides Enzo, as well
-as ensure that the other codes we support -- Orion, Tiger, etc -- are
-well-supported.
-
-`A page has been set up <http://yt.enzotools.org/wiki/AddingSupportForANewCode>`_
-on the Trac site to describe the method of adding support for a new code to
-``yt``. Please feel free to use it as a reference, but if you would like some
-assistance, drop a line to one of the mailing lists (see :ref:`mailing-list`)
-for more help.
-
-GUIs and Interactive Exploration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The 1.7 release adds some functionality for interactive exploration of data,
-but this could be greatly expanded. In particular, the volume rendering could
-be converted to a hardware based volume renderer (some simple sketches of this
-exist in the mercurial repository), the VTK interface could be improved, and
-the various components that form the interface for examining data could be
-integrated.
-
-Simulated Observations
-^^^^^^^^^^^^^^^^^^^^^^
-
-The functionality to construct simulated observations is an end goal for
-``yt``. Transforming simulation output into mock observations is the Stanley
-Cup.
-
-Bug Fixes
----------
-
-If you have simple bug fixes, please feel free to attach them to a ticket on
-the `bug tracker <http://yt.enzotools.org/newticket/>`_ (you might have to
-`register <http://yt.enzotools.org/register>`_ first) or to email them to one
-of the developers directly. We're always happy to hear about the things we've
-done wrong, and how you've fixed them!
-
-Licensing
----------
-
-All contributed code must be GPL-compatible; we ask that you consider licensing
-under the GPL version 3, but we will consider submissions of code that are
-BSD-like licensed as well. If you'd rather not license in this manner, but
-still want to contribute, just drop me a line and I'll put a link on the main
-wiki page to wherever you like!
-
-Fields and Extensions
----------------------
-
-``yt`` comes with a bunch of derived fields. However, if you have constructed
-some that add interesting analysis quantities, please feel free to send them to
-one of the developers!
-
-Additionally, if you have a sub-module that extends ``yt`` in a fun or exciting
-way, we'd be very happy to include it. Recently we've added light cone
-generators, halo profilers, and work is even ongoing on a parallel halo finder!
-
-.. _free_repo_space:
-
-Analysis Code and Examples
---------------------------
-
-Because ``yt`` can be a bit difficult to become fully acquainted with, we
-encourage you to share your analysis scripts. Specifically, we will provide
-you with free repository space to store any analysis scripts that went into the
-writing of a paper. Through this, we hope to build up a library not only of
-usage-cases, but of real-world examples of plot generation and data analysis.
-
-If you are interested in submitting your scripts, please contact Matt Turk at
-``matthewturk at gmail.com``, or just create a repository on BitBucket and send
-over the URL!
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/source/advanced/developing.rst Fri Feb 25 23:36:18 2011 -0500
@@ -0,0 +1,247 @@
+.. _contributing-code:
+
+How to Develop yt
+=================
+
+yt is a community project!
+
+We are very happy to accept patches, features, and bugfixes from any member of
+the community! yt is developed using mercurial, primarily because it enables
+very easy and straightforward submission of changesets. We're eager to hear
+from you, and if you are developing yt, we encourage you to subscribe to the
+`developer mailing list
+<http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
+
+Please feel free to hack around, commit changes, and send them upstream. If
+you're new to Mercurial, these three resources are pretty great for learning
+the ins and outs:
+
+ * `http://hginit.com`_
+ * `http://hgbook.red-bean.com/read/`_
+ * `http://mercurial.selenic.com/`_
+
+Keep in touch, and happy hacking! We also provide doc/coding_styleguide.txt
+and an example of a fiducial docstring in doc/docstring_example.txt. Please
+read them before hacking on the codebase, and feel free to email any of the
+mailing lists for help with the codebase.
+
+Licensing
+--------
+
+All code in yt should be under the GPL-3 (preferred) or a compatible license.
+
+How To Get The Source Code
+--------------------------
+
+yt is hosted on BitBucket, and you can see all of the yt repositories at
+`http://hg.enzotools.org/`_. With the yt installation script you should have a
+copy of Mercurial. You can clone the repository like so:
+
+.. code-block:: bash
+
+ $ hg clone http://hg.enzotools.org/yt/
+
+You can update to any branch or revision by executing the command:
+
+.. code-block:: bash
+
+ $ hg up -C some_revision_specifier
+
+Specifying a branch name in the revspec will update to the latest revision on
+that branch. If you ran the installation script, you can tell Python to use a
+different version of the library by executing:
+
+.. code-block:: bash
+
+ $ python2.6 setup.py develop
+
+This will rebuild all C modules as well.
+
+How To Submit Changes
+---------------------
+
+You can submit changes a couple different ways, but the easiest is to use the
+"fork" mechanism on BitBucket. Just go to the "fork" page at:
+
+`http://hg.enzotools.org/yt/fork`_
+
+and you're all set, ready to go. You'll have to either clone a new copy of the
+repository or edit .hg/hgrc to point to the location of your new fork, first,
+though.
+
+When you're ready to submit them to the main repository, simply go to:
+
+`http://hg.enzotools.org/yt/fork`_
+
+Make sure you notify "yt_analysis" and put in a little description. That'll
+notify the core developers that you've got something ready to submit, and we
+will review it an (hopefully!) merge it in. If it goes well, you may end up
+with push access to the main repository.
+
+How To Read The Source Code
+---------------------------
+
+yt is organized into several sub-packages, each of which governs a different
+conceptual regime.
+
+ frontends
+ This is where interfaces to codes are created. Within each subdirectory of
+ yt/frontends/ there must exist the following files, even if empty:
+
+ * data_structures.py, where subclasses of AMRGridPatch, StaticOutput and
+ AMRHierarchy are defined.
+ * io.py, where a subclass of IOHandler is defined.
+ * misc.py, where any miscellaneous functions or classes are defined.
+ * definitions.py, where any definitions specific to the frontend are
+ defined. (i.e., header formats, etc.)
+
+ visualization
+ This is where all visualization modules are stored. This includes plot
+ collections, the volume rendering interface, and pixelization frontends.
+
+ data_objects
+ All objects that handle data, processed or unprocessed, not explicitly
+ defined as visualization are located in here. This includes the base
+ classes for data regions, covering grids, time series, and so on. This
+ also includes derived fields and derived quantities.
+
+ analysis_modules
+ This is where all mechanisms for processing data live. This includes
+ things like clump finding, halo profiling, halo finding, and so on. This
+ is something of a catchall, but it serves as a level of greater
+ abstraction that simply data selection and modification.
+
+ gui
+ This is where all GUI components go. Typically this will be some small
+ tool used for one or two things, which contains a launching mechanism on
+ the command line.
+
+ utilities
+ All broadly useful code that doesn't clearly fit in one of the other
+ categories goes here.
+
+How To Use Branching
+--------------------
+
+If you are planning on making a large change to the code base that may not be
+ready for many commits, or if you are planning on breaking some functionality
+and rewriting it, you are encouraged to create a new named branch. You can
+mark the current repository as a new named branch by executing:
+
+.. code-block:: bash
+
+ $ hg branch new_feature_name
+
+The next commit and all subsequent commits will be contained within that named
+branch. At this point, add your branch here:
+
+`http://yt.enzotools.org/wiki/ExistingBranches`_
+
+To merge changes in from another branch, you would execute:
+
+.. code-block:: bash
+
+ $ hg merge some_other_branch
+
+Note also that you can use revision specifiers instead of "some_other_branch".
+When you are ready to merge back into the main branch, execute this process:
+
+.. code-block:: bash
+
+ $ hg merge name_of_main_branch
+ $ hg commit --close-branch
+ $ hg up -C name_of_main_branch
+ $ hg merge name_of_feature_branch
+ $ hg commit
+
+When you execute the merge you may have to resolve conflicts. Once you resolve
+conflicts in a file, you can mark it as resolved by doing:
+
+.. code-block:: bash
+
+ $ hg resolve -m path/to/conflicting/file.py
+
+Please be careful when resolving conflicts in files.
+
+Once your branch has been merged in, mark it as closed on the wiki page.
+
+Project Ideas
+-------------
+
+There are lots of places in ``yt`` where new extensions could be added, or new
+functionality put in place. Here are a few.
+
+Adding Support for a New Code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``yt`` strives to be a general-purpose analysis tool for astrophysical data.
+To that end, we'd like to short up our support for codes besides Enzo, as well
+as ensure that the other codes we support -- Orion, Tiger, etc -- are
+well-supported.
+
+`A page has been set up <http://yt.enzotools.org/wiki/AddingSupportForANewCode>`_
+on the Trac site to describe the method of adding support for a new code to
+``yt``. Please feel free to use it as a reference, but if you would like some
+assistance, drop a line to one of the mailing lists (see :ref:`mailing-list`)
+for more help.
+
+GUIs and Interactive Exploration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The 1.7 release adds some functionality for interactive exploration of data,
+but this could be greatly expanded. In particular, the volume rendering could
+be converted to a hardware based volume renderer (some simple sketches of this
+exist in the mercurial repository), the VTK interface could be improved, and
+the various components that form the interface for examining data could be
+integrated.
+
+Simulated Observations
+^^^^^^^^^^^^^^^^^^^^^^
+
+The functionality to construct simulated observations is an end goal for
+``yt``. Transforming simulation output into mock observations is the Stanley
+Cup.
+
+Bug Fixes
+---------
+
+If you have simple bug fixes, please feel free to attach them to a ticket on
+the `bug tracker <http://yt.enzotools.org/newticket/>`_ (you might have to
+`register <http://yt.enzotools.org/register>`_ first) or to email them to one
+of the developers directly. We're always happy to hear about the things we've
+done wrong, and how you've fixed them!
+
+Licensing
+---------
+
+All contributed code must be GPL-compatible; we ask that you consider licensing
+under the GPL version 3, but we will consider submissions of code that are
+BSD-like licensed as well. If you'd rather not license in this manner, but
+still want to contribute, just drop me a line and I'll put a link on the main
+wiki page to wherever you like!
+
+Fields and Extensions
+---------------------
+
+``yt`` comes with a bunch of derived fields. However, if you have constructed
+some that add interesting analysis quantities, please feel free to send them to
+one of the developers!
+
+Additionally, if you have a sub-module that extends ``yt`` in a fun or exciting
+way, we'd be very happy to include it. Recently we've added light cone
+generators, halo profilers, and work is even ongoing on a parallel halo finder!
+
+.. _free_repo_space:
+
+Analysis Code and Examples
+--------------------------
+
+Because ``yt`` can be a bit difficult to become fully acquainted with, we
+encourage you to share your analysis scripts. Specifically, we will provide
+you with free repository space to store any analysis scripts that went into the
+writing of a paper. Through this, we hope to build up a library not only of
+usage-cases, but of real-world examples of plot generation and data analysis.
+
+If you are interested in submitting your scripts, please contact Matt Turk at
+``matthewturk at gmail.com``, or just create a repository on BitBucket and send
+over the URL!
--- a/source/advanced/index.rst Fri Feb 25 23:34:29 2011 -0500
+++ b/source/advanced/index.rst Fri Feb 25 23:36:18 2011 -0500
@@ -14,4 +14,4 @@
creating_derived_quantities
creating_datatypes
debugdrive
- contribution
+ developing
http://bitbucket.org/yt_analysis/yt-doc/changeset/eadec86c65db/
changeset: r26:eadec86c65db
user: MatthewTurk
date: 2011-02-26 06:12:43
summary: Fleshing out and merging the developer guides
affected #: 1 file (3.4 KB)
--- a/source/advanced/developing.rst Fri Feb 25 23:36:18 2011 -0500
+++ b/source/advanced/developing.rst Fri Feb 25 21:12:43 2011 -0800
@@ -16,9 +16,9 @@
you're new to Mercurial, these three resources are pretty great for learning
the ins and outs:
- * `http://hginit.com`_
- * `http://hgbook.red-bean.com/read/`_
- * `http://mercurial.selenic.com/`_
+ * http://hginit.com/
+ * http://hgbook.red-bean.com/read/
+ * http://mercurial.selenic.com/
Keep in touch, and happy hacking! We also provide doc/coding_styleguide.txt
and an example of a fiducial docstring in doc/docstring_example.txt. Please
@@ -28,13 +28,17 @@
Licensing
--------
-All code in yt should be under the GPL-3 (preferred) or a compatible license.
+All contributed code must be GPL-compatible; we ask that you consider licensing
+under the GPL version 3, but we will consider submissions of code that are
+BSD-like licensed as well. If you'd rather not license in this manner, but
+still want to contribute, just drop me a line and I'll put a link on the main
+wiki page to wherever you like!
How To Get The Source Code
--------------------------
yt is hosted on BitBucket, and you can see all of the yt repositories at
-`http://hg.enzotools.org/`_. With the yt installation script you should have a
+http://hg.enzotools.org/ . With the yt installation script you should have a
copy of Mercurial. You can clone the repository like so:
.. code-block:: bash
@@ -63,7 +67,7 @@
You can submit changes a couple different ways, but the easiest is to use the
"fork" mechanism on BitBucket. Just go to the "fork" page at:
-`http://hg.enzotools.org/yt/fork`_
+http://hg.enzotools.org/yt/fork
and you're all set, ready to go. You'll have to either clone a new copy of the
repository or edit .hg/hgrc to point to the location of your new fork, first,
@@ -71,9 +75,9 @@
When you're ready to submit them to the main repository, simply go to:
-`http://hg.enzotools.org/yt/fork`_
+http://hg.enzotools.org/yt/pull
-Make sure you notify "yt_analysis" and put in a little description. That'll
+Make sure you notify ``yt_analysis`` and put in a little description. That'll
notify the core developers that you've got something ready to submit, and we
will review it an (hopefully!) merge it in. If it goes well, you may end up
with push access to the main repository.
@@ -84,39 +88,39 @@
yt is organized into several sub-packages, each of which governs a different
conceptual regime.
- frontends
+ ``frontends``
This is where interfaces to codes are created. Within each subdirectory of
yt/frontends/ there must exist the following files, even if empty:
- * data_structures.py, where subclasses of AMRGridPatch, StaticOutput and
- AMRHierarchy are defined.
- * io.py, where a subclass of IOHandler is defined.
- * misc.py, where any miscellaneous functions or classes are defined.
- * definitions.py, where any definitions specific to the frontend are
+ * ``data_structures.py``, where subclasses of AMRGridPatch, StaticOutput
+ and AMRHierarchy are defined.
+ * ``io.py``, where a subclass of IOHandler is defined.
+ * ``misc.py``, where any miscellaneous functions or classes are defined.
+ * ``definitions.py``, where any definitions specific to the frontend are
defined. (i.e., header formats, etc.)
- visualization
+ ``visualization``
This is where all visualization modules are stored. This includes plot
collections, the volume rendering interface, and pixelization frontends.
- data_objects
+ ``data_objects``
All objects that handle data, processed or unprocessed, not explicitly
defined as visualization are located in here. This includes the base
classes for data regions, covering grids, time series, and so on. This
also includes derived fields and derived quantities.
- analysis_modules
+ ``analysis_modules``
This is where all mechanisms for processing data live. This includes
things like clump finding, halo profiling, halo finding, and so on. This
is something of a catchall, but it serves as a level of greater
abstraction that simply data selection and modification.
- gui
+ ``gui``
This is where all GUI components go. Typically this will be some small
tool used for one or two things, which contains a launching mechanism on
the command line.
- utilities
+ ``utilities``
All broadly useful code that doesn't clearly fit in one of the other
categories goes here.
@@ -133,9 +137,8 @@
$ hg branch new_feature_name
The next commit and all subsequent commits will be contained within that named
-branch. At this point, add your branch here:
-
-`http://yt.enzotools.org/wiki/ExistingBranches`_
+branch. At this point, add your branch on the `ExistingBranches
+<http://yt.enzotools.org/wiki/ExistingBranches>`_ wiki page.
To merge changes in from another branch, you would execute:
@@ -143,8 +146,9 @@
$ hg merge some_other_branch
-Note also that you can use revision specifiers instead of "some_other_branch".
-When you are ready to merge back into the main branch, execute this process:
+Note also that you can use revision specifiers instead of
+``some_other_branch``. When you are ready to merge back into the main branch,
+execute this process:
.. code-block:: bash
@@ -165,6 +169,85 @@
Once your branch has been merged in, mark it as closed on the wiki page.
+Code Style Guide
+----------------
+
+To keep things tidy, we try to stick with a couple simple guidelines.
+
+General Guidelines
+^^^^^^^^^^^^^^^^^^
+
+ * In general, follow `PEP-8 <http://www.python.org/dev/peps/pep-0008/>`_ guidelines.
+ * Classes are ConjoinedCapitals, methods and functions are
+ ``lowercase_with_underscores.``
+ * Use 4 spaces, not tabs, to represent indentation.
+ * Line widths should not be more than 80 characters.
+ * Do not use nested classes unless you have a very good reason to, such as
+ requiring a namespace or class-definition modification. Classes should live
+ at the top level. ``__metaclass__`` is exempt from this.
+ * Do not use unecessary parenthesis in conditionals. ``if((something) and
+ (something_else))`` should be rewritten as ``if something and
+ something_else``. Python is more forgiving than C.
+ * Avoid copying memory when possible. For example, don't do ``a =
+ a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3`` should be
+ ``na.multiply(a, 3, a)``.
+ * In general, avoid all double-underscore method names: ``__something`` is
+ usually unnecessary.
+ * Doc strings should describe input, output, behavior, and any state changes
+ that occur on an object. See the file `doc/docstring_example.txt` for a
+ fiducial example of a docstring.
+
+API Guide
+^^^^^^^^^
+
+ * Do not import "*" from anything other than ``yt.funcs``.
+ * Internally, only import from source files directly; instead of: ``from
+ yt.visualization.api import PlotCollection`` do
+ ``from yt.visualization.plot_collection import PlotCollection``.
+ * Numpy is to be imported as ``na`` not ``np``. While this may change in the
+ future, for now this is the correct idiom.
+ * Do not use too many keyword arguments. If you have a lot of keyword
+ arguments, then you are doing too much in ``__init__`` and not enough via
+ parameter setting.
+ * In function arguments, place spaces before commas. ``def something(a,b,c)``
+ should be ``def something(a, b, c)``.
+ * Don't create a new class to replicate the functionality of an old class --
+ replace the old class. Too many options makes for a confusing user
+ experience.
+ * Parameter files external to yt are a last resort.
+ * The usage of the ``**kwargs`` construction should be avoided. If they
+ cannot be avoided, they must be explained, even if they are only to be
+ passed on to a nested function.
+
+Variable Names and Enzo-isms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ * Avoid Enzo-isms. This includes but is not limited to:
+
+ + Hard-coding parameter names that are the same as those in Enzo. The
+ following translation table should be of some help. Note that the
+ parameters are now properties on a StaticOutput subclass: you access them
+ like ``pf.refine_by`` .
+
+ - ``RefineBy `` => `` refine_by``
+ - ``TopGridRank `` => `` dimensionality``
+ - ``TopGridDimensions `` => `` domain_dimensions``
+ - ``InitialTime `` => `` current_time``
+ - ``DomainLeftEdge `` => `` domain_left_edge``
+ - ``DomainRightEdge `` => `` domain_right_edge``
+ - ``CurrentTimeIdentifier `` => `` unique_identifier``
+ - ``CosmologyCurrentRedshift `` => `` current_redshift``
+ - ``ComovingCoordinates `` => `` cosmological_simulation``
+ - ``CosmologyOmegaMatterNow `` => `` omega_matter``
+ - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
+ - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
+
+ + Do not assume that the domain runs from 0 to 1. This is not true
+ everywhere.
+
+ * Variable names should be short but descriptive.
+ * No globals!
+
Project Ideas
-------------
@@ -203,7 +286,7 @@
Cup.
Bug Fixes
----------
+^^^^^^^^^
If you have simple bug fixes, please feel free to attach them to a ticket on
the `bug tracker <http://yt.enzotools.org/newticket/>`_ (you might have to
@@ -211,30 +294,20 @@
of the developers directly. We're always happy to hear about the things we've
done wrong, and how you've fixed them!
-Licensing
----------
-
-All contributed code must be GPL-compatible; we ask that you consider licensing
-under the GPL version 3, but we will consider submissions of code that are
-BSD-like licensed as well. If you'd rather not license in this manner, but
-still want to contribute, just drop me a line and I'll put a link on the main
-wiki page to wherever you like!
-
Fields and Extensions
----------------------
+^^^^^^^^^^^^^^^^^^^^^
``yt`` comes with a bunch of derived fields. However, if you have constructed
some that add interesting analysis quantities, please feel free to send them to
one of the developers!
Additionally, if you have a sub-module that extends ``yt`` in a fun or exciting
-way, we'd be very happy to include it. Recently we've added light cone
-generators, halo profilers, and work is even ongoing on a parallel halo finder!
+way, we'd be very happy to include it.
.. _free_repo_space:
Analysis Code and Examples
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
Because ``yt`` can be a bit difficult to become fully acquainted with, we
encourage you to share your analysis scripts. Specifically, we will provide
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