Metadata-Version: 1.0
Name: TheLandlab
Version: 0.1.4
Summary: Plugin-based component modeling tool.
Home-page: https://csdms.colorado.edu/trac/landlab
Author: Eric Hutton
Author-email: eric.hutton@colorado.edu
License: UNKNOWN
Description: ===========
        The Landlab
        ===========
        
        :package name: TheLandlab
        :version: 0.1
        :release date: 2013-03-24
        :authors:
          Greg Tucker,
          Nicole Gasparini,
          Erkan Istanbulluoglu,
          Daniel Hobley,
          Sai Nudurupati,
          Jordan Adams,
          Eric Hutton
        
        :url: http://csdms.colorado.edu/trac/landlab
        
        :license: MIT
        
        Install
        =======
        
        Installing a release
        --------------------
        
        We don't have any releases of The Landlab yet so this doesn't work right now.
        However, once we have a stable release, this is how users will install our
        software on their machine::
        
            $ pip install TheLandlab
        
        This will install Landlab as well as any prerequisite packages (required packages
        are listed in setup.py).
        
        Installing from a source distribution
        -------------------------------------
        
        To install the landlab package from a source distribution (like what you get with
        a Subversion checkout), run the setup.py script with the install argument::
        
            $ python setup.py install
        
        This will put the landlab package into a system-wide location so that you can
        import landlab from any python session. It will also install any required
        packages.
        
        Note that if you are developing landlab you will probably not want to do this!
        If you do, you would have to run this command everytime you make a change to
        the code. Instead, you want to install the package in "development mode". See
        below in the "Development Environment" section for details on how to do this.
        
        
        ----------------------
        Developing The Landlab
        ----------------------
        
        This section describes one possible workflow when developing The Landlab.
        
        Using Subversion
        ================
        
        The standard resource for Subversion "Version Control with Subversion" book.
        It's available online and is completely *free*!
        
        http://svnbook.red-bean.com/
        
        
        Checkout a copy of the source
        -----------------------------
        
        Use Subversion to checkout the latest version of the source code::
        
            $ svn co https://csdms.colorado.edu/svn/TheLandlab/trunk landlab
        
        Alternatively, if you already have a working copy of the repository you may want
        to update it with changes that others have committed to the repository::
        
            $ svn update
        
        Review your changes
        -------------------
        
        Now that you've made changes to some files, you'll probably want to have a
        look at what you've done. To see what it is you've changed since your last
        commit (or since you last checkout), use the status command::
        
            $ svn status
        
        Use the Subversion diff command to see the differences between your copy and the
        copy that you checked out::
        
            $ svn diff <changed_file>
        
        where *<changed_file>* is the name of the file you've made changes to. If you
        don't list any file names, this command will print the differences for *all*
        files that have changes.
        
        Commit your changes to the repository
        -------------------------------------
        
        Once you have made changes to your copy of the source and are happy with the
        changes, you can commit them back to the repository::
        
            $ svn commit
        
        This will commit all changes that you have made under the current directory. If
        you only want to commit changes to a file or two, you can list the file names
        separately on the command line::
        
            $ svn commit <one_file> <another_file>
        
        
        ---------------------------
        The Development Environment
        ---------------------------
        
        Once I have a working copy of The Landlab source code, I use the pip command to
        install a development version of the code. If I'm in the base landlab folder
        (the folder that contains setup.py), I run the following::
        
            $ pip install -e .
        
        This sets up python so that it knows where the landlab package is when try to
        import it - regardless of what directory you are in. This allows python commands
        like::
        
            >>> import landlab
            >>> from landlab import craters
        
        to work. If you didn't do this you might start getting errors that contain 
        something like::
        
            ImportError: No module named landlab
        
        To uninstall your development version of landlab::
        
            $ pip uninstall TheLandlab
        
        
        ------------------
        Running Unit Tests
        ------------------
        
        Immediatly after update your working copy of the code (or checking out a new
        version) I will normally run the unit tests for the package to make sure nothing
        is broken. You can do this with setup.py::
        
            $ python setup.py test
        
        You should also probably do this before commiting changes to the repository to
        make sure you didn't break things.
        
        
        ------------
        Coding Style
        ------------
        
        Because Python is so flexible style-wise, please try to stick to the coding
        style described by PEP8,
        
        http://www.python.org/dev/peps/pep-0008/
        
        An easy way to make sure that you've done this is by running the pep8 command
        on each file that you edit. If you don't have pep8 installed, you will have to
        install it with::
        
            $ pip install pep8
        
        Now you can run it on a Python source file. For instance::
        
            $ pep8 craters.py
        
        At first, this will probably return lots of problems with you source file. Don't
        worry though, it won't take long to get used to the coding style and be able to
        write compatible code straigt away. If we stick to this it will make it much
        easier to read the code written by any one of us.
        
        
        -----------------------
        Build API Documentation
        -----------------------
        
        You can build documentation for the LandLab API using Sphinx. Once you have set
        up your envrionment to properly import landlab, you can generate the necessary
        sphinx files with::
        
            $ python setup.py build_sphinx
        
        This will put a bunch of files in the docs folder. The HTML documentation will
        be under the docs/_build/html/ folder. Pointing your browser to index.html
        under this folder will give you the top-level page for the documentation. This
        entire folder is relocatable, so if you would like your documentation elsewhere
        you can easily move the folder around.
        
        If you have added, removed, or renamed files you may need to regenerate some of
        the sphinx files and rebuild the api docs. If you have Sphinx installed, you can
        do this with (from the directory that contains setup.py)::
        
            $ sphinx-apidoc -o docs landlab
        
        
        Happy Landlab-ing!
        ==================
        
Platform: UNKNOWN
