Commits

Chris Mutel committed 3c5beda

Big improvements in docs

  • Participants
  • Parent commits 11c9653

Comments (0)

Files changed (13)

 include *.txt
-include bw2calc/*.py
-include bw2calc/io/*.py
-include bw2calc/proxies/*.py
+include brightway2/*.py
+include brightway2/io/*.py
+include brightway2/proxies/*.py

brightway2/_config.py

 
         To set the environment variable:
 
-        * Unix/Max: ``export BRIGHTWAY2_DIR=/path/to/brightway2/directory``
+        * Unix/Mac: ``export BRIGHTWAY2_DIR=/path/to/brightway2/directory``
         * Windows: ``set BRIGHTWAY2_DIR=\path\to\brightway2\directory``
 
         """

brightway2/database.py

 
     @property
     def version(self):
+        """The current version number (integer) of this database.
+
+        Returns:
+            Version number
+
+        """
         return databases.version(self.database)
 
     def query(self, *queries):
     def copy(self, name):
         """Make a copy of the database.
 
+        Internal links within the database will be updated to match the new database name.
+
         Args:
             *name* (str): Name of the new database.
 
         new_database.write(data)
 
     def backup(self):
-        """Save a backup to ``backups`` folder."""
+        """Save a backup to ``backups`` folder.
+
+        Returns:
+            Filepath of backup.
+
+        """
         data = self.load()
         filepath = os.path.join(config.dir, "backups", self.filename() + \
             ".%s.backup" % int(time()))
 
         .. warning:: Reverted changes can be overwritten.
 
+        Args:
+            *version* (int): Number of the version to revert to.
+
         """
         assert version in [x[0] for x in self.versions()], "Version not found"
         self.backup()
     def validate(self, data):
         """Validate data. Must be called manually.
 
+        Raises ``voluptuous.Invalid`` if data does not validate.
+
         Args:
             *data* (dict): The data, in its processed form.
 
         """
         db_validator(data)
-        return True
 
     def filename(self, version=None):
-        """Filename for given version; Default is current."""
+        """Filename for given version; Default is current.
+
+        Returns:
+            Filename (not path)
+
+        """
         return "%s.%i.pickle" % (self.database,
             version or self.version)
 
             raise MissingIntermediateData("This version (%i) not found" % version)
 
     def versions(self):
-        """Return list of (version, datetime created) tuples"""
+        """Get a list of available versions of this database.
+
+        Returns:
+            List of (version, datetime created) tuples.
+
+        """
         directory = os.path.join(config.dir, "intermediate")
         files = natural_sort(filter(
             lambda x: ".".join(x.split(".")[:-2]) == self.database,

brightway2/io/import_ecospold.py

 
 
 class EcospoldImporter(object):
+    """Import inventory datasets from ecospold XML format.
+
+    Does not have any arguments; instead, instantiate the class, and then import using the ``importer`` method, i.e. ``EcospoldImporter().importer(filepath)``."""
     def importer(self, path, name, depends=["biosphere", ]):
+        """Import an inventory dataset, or a directory of inventory datasets.
+
+        Args:
+            *path* (str): A filepath or directory.
+
+        """
         data = []
         log = get_logger(name)
         log.critical(u"Starting import of %s (from %s)" % (name, path))
         data = dict([((name, int(o["code"])), o) for o in data])
 
         manager = Database(name)
-        manager.register("Ecospold 1", depends, len(data))
+        manager.register(("Ecospold", 1), depends, len(data))
         manager.write(data)
 
         pbar.finish()

brightway2/io/import_method.py

 
 
 class EcospoldImpactAssessmentImporter(object):
-    """
-Import impact assessment methods and weightings from ecospold XML format.
-    """
+    """Import impact assessment methods and weightings from ecospold XML format.
+
+Does not have any arguments; instead, instantiate the class, and then import using the ``importer`` method, i.e. ``EcospoldImpactAssessmentImporter().importer(filepath)``."""
     def importer(self, path):
+        """Import an impact assessment method, or a directory of impact assessment methods.
+
+        Args:
+            *path* (str): A filepath or directory.
+
+        """
         if os.path.isdir(path):
             files = [os.path.join(path, filter(lambda x: x[-4:].lower(
                 ) == ".xml", os.listdir(path)))]

brightway2/query.py

             + "\n".join(["%s: %s" % (key, data[key]["name"]) for key in data])
 
     def sort(self, field, reverse=False):
-        """Sort the filtered dataset. Acts (effectively) in place; does not return anything.
+        """Sort the filtered dataset. Operates in place; does not return anything.
 
         Args:
             *field* (str): The key used for sorting.
 
         """
         self.result = collections.OrderedDict(sorted(self.result.iteritems(),
-            key=lambda t: t[1].get(field, None)), reverse=reverse)
+            key=lambda t: t[1].get(field, None), reverse=reverse))
 
     # Generic dictionary methods
     def __len__(self):
 class Query(object):
     """A container for a set of filters applied to a dataset.
 
-    Filters are applied by calling the ``Query`` object, and passing the dataset to filter as the argument. Calling a ``Query`` returns a ``Result`` object with the filtered dataset.
+    Filters are applied by calling the ``Query`` object, and passing the dataset to filter as the argument. Calling a ``Query`` with some data returns a ``Result`` object with the filtered dataset.
 
     Args:
-        *filters* (``Filter``(s)): One or more Filter objects.
+        *filters* (filters): One or more ``Filter`` objects.
 
     """
     def __init__(self, *filters):
 
 
 class Filter(object):
+    """A filter on a dataset.
+
+    The following functions are supported:
+
+        * "<", "<=", "==", ">", ">=": Mathematical relations
+        * "is", "not": Identity relations. Work on any Python object.
+        * "in", "notin": List or string relations.
+        * "iin", "iis", "inot": Case-insensitive string relations.
+        * "len": Length relation.
+
+    In addition, any function which defines a relationship between an input and an output can also be used.
+
+    Examples:
+
+        * All ``name`` values are *foo*: ``Filter("name", "is", "foo")``
+        * All ``name`` values include the string *foo*: ``Filter("name", "in", "foo")``
+        * Category (a list of categories and subcategories) includes *foo*: ``Filter("category", "in", "foo")``
+
+    Args:
+        *key* (str): The field to filter on.
+        *function* (str or object): One of the pre-defined filters, or a callable object.
+        *value* (object): The value to test against.
+
+    Returns:
+        A ``Result`` object which wraps a new data dictionary.
+
+    """
     def __init__(self, key, function, value):
         self.key = key
         self.function = function

docs/databases.rst

-A database is a collection of data
-**********************************
-
-An inventory database is one of the core components of Brightway2, but this doesn't mean it has a rigid structure. Databases can have thousands of processes, or only one. Brightway2 uses the idea of a database to organize your data.
-
-The Database class
-==================
-
-.. autoclass:: brightway2.Database
-	:members:
-	:inherited-members:
-
-.. autoclass:: brightway2.Method
-	:members:
-	:inherited-members:
 
 First, download the latest version of `Python (x,y) <https://code.google.com/p/pythonxy/wiki/Downloads>`_, and install it. This is the easiest way to get the `NumPy <http://numpy.scipy.org/>`_ and `SciPy <http://scipy.org/>`_ libraries.
 
+* `Python (x,y) <https://code.google.com/p/pythonxy/wiki/Downloads>`_
+
 Second, download and install the XML processing library `lxml <http://pythonxy.googlecode.com/files/lxml-3.0.1-1_py27.exe>`_.
 
+* `lxml <http://pythonxy.googlecode.com/files/lxml-3.0.1-1_py27.exe>`_
+
 Third, open a command prompt (Start -> Run), and type in the following:
 
-.. pull-quote::
+.. code-block:: bash
 	
 	pip install bw2all
 
-Finally, in another command prompt, start Brightway2:
+Finally, again in the command prompt, start Brightway2:
 
-.. pull-quote::
+.. code-block:: bash
 
 	bw2-web.py
 
 
    installation
    introduction
-   databases
+   usage
    querying
    technical
    changelog

docs/installation.rst

-First steps
-***********
-
 Installation
-============
+************
 
 Windows 
--------
+=======
 
 Although Brightway2 is relatively simple, installation of the numerical and scientific libraries can be difficult as there is no default compilers installed on most Windows machines. The only sensible way is to use a precompiled set of packages, such as `Python (x,y) <https://code.google.com/p/pythonxy/wiki/Downloads>`_ or the `Enthought Python Distribution <http://www.enthought.com/products/epd.php>`_. If using Python (x,y), be sure to install `lxml <http://pythonxy.googlecode.com/files/lxml-3.0.1-1_py27.exe>`_ separately.
 
 
 After the basic installation, you can install all additional Brightway2 packages and dependencies in one command in the command shell:
 
-.. pull-quote::
+.. code-block:: bash
 	
 	pip install bw2all
 
+If you want to develop with Brightway, then don't install the metapackage. Instead, first install `virtualenv <http://www.virtualenv.org/>`_ and `virtualenv for Powershell <https://bitbucket.org/guillermooo/virtualenvwrapper-powershell>`_:
+
+.. code-block:: bash
+    
+    pip install virtualenv virtualenvwrapper-powershell
+    mkvirtualenv bw2 --system-site-packages
+
+Before you do anything else, go back and read what ``virtualenv`` does :) Now you can install packages into your isolated environment:
+
+.. code-block:: bash
+
+    pip install progressbar flask docopt voluptuous requests bw-stats-toolkit nose sphinx
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2#egg=brightway2
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-calc#egg=bw2calc
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-ui#egg=bw2ui
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-analyzer#egg=bw2analyzer
+
 Max OS X
---------
+========
 
 There are two main alternatives for installing packages on OS X: `Macports <http://www.macports.org/>`_ and `Homebrew <http://mxcl.github.com/homebrew/>`_. Brightway2 is developed primarily on OS X using Macports, but as it depends on a few standard libraries, either alternative should work well. Homebrew users will have to adapt the following instructions.
 
 
 Next, install the needed Python libraries using this command in the Terminal:
 
-.. pull-quote::
+.. code-block:: bash
 
-	sudo port install py27-scipy py27-numpy py27-nose py27-pip py27-progressbar py27-cython py27-libxml2
+	sudo port install py27-scipy py27-numpy py27-pip py27-progressbar py27-libxml2
 
-Finally, install Brightway2, using another Terminal command:
+To only work with Brightway2, finish your installation using another Terminal command:
 
-.. pull-quote::
+.. code-block:: bash
 	
 	sudo pip install bw2all
 
+If you want to develop with Brightway, then don't install the metapackage. Instead, we will create a `virtualenv <http://www.virtualenv.org/>`_ for the Brightway2 dependencies and framework. First, read what ``virtualenv`` does; then, run the following in a Terminal:
+
+.. code-block:: bash
+    
+    sudo port install virtualenv virtualenvwrapper py27-cython py27-nose py27-sphinx py27-flask py27-requests
+    mkvirtualenv bw2 --system-site-packages
+    pip install docopt voluptuous bw-stats-toolkit
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2#egg=brightway2
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-calc#egg=bw2calc
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-ui#egg=bw2ui
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-analyzer#egg=bw2analyzer
+
 Linux
------
+=====
 
-General instructions are provided for Ubuntu; people using other distributions are assumed smart to be enough to adapt as necessary.
+General instructions are provided for Ubuntu; people using other distributions are assumed smart to be enough to adapt as necessary. See also `Platform-agnostic`_ instructions above.
 
 First, install the required ``apt`` packages. You can select them in the graphical interface, or through one command in the terminal:
 
-.. pull-quote::
+.. code-block:: bash
 
-	sudo apt-get install py27-scipy py27-numpy py27-nose py27-pip py27-progressbar py27-cython py27-libxml2
+	sudo apt-get install python-scipy python-numpy python-nose python-pip python-progressbar python-libxml2 python-sphinx python-virtualenv python-virtualenvwrapper
 
 Then install Brightway2 using another terminal command:
 
-.. pull-quote::
+.. code-block:: bash
 
 	sudo pip install bw2all
 
-Usage
-=====
+If you want to develop with Brightway, then don't install the metapackage. Instead, we will create a `virtualenv <http://www.virtualenv.org/>`_ for the Brightway2 dependencies and framework. First, read what ``virtualenv`` does; then, run the following in a Terminal:
 
-Brightway2 is now installed, and there are three ways to access the various parts of the framework.
+.. code-block:: bash
+    
+    mkvirtualenv bw2 --system-site-packages
+    pip install docopt voluptuous bw-stats-toolkit flask requests
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2#egg=brightway2
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-calc#egg=bw2calc
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-ui#egg=bw2ui
+    pip install -e hg+https://bitbucket.org/cmutel/brightway2-analyzer#egg=bw2analyzer
 
-Web interface
--------------
+Platform-agnostic
+=================
 
-The web user interface can be started by running:
+Installation of Brightway2 has two steps. First, install the following scientific and numeric libraries:
 
-.. pull-quote::
-	
-	bw2-web.py
+* scipy >= 0.10
+* numpy >= 1.6
+* lxml
+* pip
 
-Running the web interface for the first time will also give you instructions on setting up databases and making LCA calculations.
+.. warning:: Make sure that ``SciPy`` builds with support for `UMFPACK <http://www.cise.ufl.edu/research/sparse/umfpack/>`_; you may need to also install `scikits-umpack <http://scikits.appspot.com/umfpack>`_.
+
+Second, install the Brightway2 metapackage:
+
+.. code-block:: bash
+    
+    pip install bw2all
+
+If you want to install packages manually, or not install everything, Brightway2 uses the following Python packages:
+
+* progressbar 
+* flask
+* docopt
+* voluptuous
+* requests
+* bw-stats-toolkit
+
+The Brightway2 packages are:
+
+* brightway2
+* bw2calc
+* bw2ui
+* bw2analyzer
+
+If you want to develop with Brightway, then you should install the following:
+
+* nose
+* sphinx
+
+.. warning:: If you are developing, it is *strongly* recommended to use `virtualenv <http://www.virtualenv.org/>`_ and `virtualenvwrapper <http://www.doughellmann.com/projects/virtualenvwrapper/>`_.

docs/introduction.rst

-Introduction to Brightway2
-**************************
+Introduction
+************
 
 Brightway2 has the following features:
 

docs/querying.rst

-Querying a database or method
-*****************************
+Searching databases
+*******************
 
-The Database class
-==================
+Brightway2 includes some simple functions for searching within databases. Because a database is a simple Python dictionary, it is relatively simple to filter and process. The strategy is to apply one (or more) ``Filter`` in a ``Query``. The return value of a ``Query`` is a ``Result``, which can printed or sorted. Queries can also be called directly from the ``Database`` object. Here is a simple example:
+
+.. code-block:: python
+
+    In [1]: from brightway2.query import *
+    In [2]: from brightway2 import *
+    In [3]: ei = Database("ecoinvent 2.2")
+    In [4]: r = ei.query(Filter("name", "in", "at long-distance pipeline"))
+    In [5]: len(r)
+    Out[5]: 8
+
+    In [6]: print r
+    Query result with 8 entries
+
+    In [7]: r
+    Out[7]: 
+    Query result: (total 8)
+    ('ecoinvent 2.2', 1427): natural gas, production DZ, at long-distance pipeline
+    ('ecoinvent 2.2', 1425): natural gas, production DE, at long-distance pipeline
+    ('ecoinvent 2.2', 1413): natural gas, at long-distance pipeline
+    ('ecoinvent 2.2', 1412): natural gas, at long-distance pipeline
+    ('ecoinvent 2.2', 1432): natural gas, production RU, at long-distance pipeline
+    ('ecoinvent 2.2', 1431): natural gas, production NO, at long-distance pipeline
+    ('ecoinvent 2.2', 1430): natural gas, production NL, at long-distance pipeline
+    ('ecoinvent 2.2', 1429): natural gas, production GB, at long-distance pipeline
+
+    In [8]: r.sort("name")
+    In [9]: r
+    Out[9]: 
+    Query result: (total 8)
+    ('ecoinvent 2.2', 1413): natural gas, at long-distance pipeline
+    ('ecoinvent 2.2', 1412): natural gas, at long-distance pipeline
+    ('ecoinvent 2.2', 1425): natural gas, production DE, at long-distance pipeline
+    ('ecoinvent 2.2', 1427): natural gas, production DZ, at long-distance pipeline
+    ('ecoinvent 2.2', 1429): natural gas, production GB, at long-distance pipeline
+    ('ecoinvent 2.2', 1430): natural gas, production NL, at long-distance pipeline
+    ('ecoinvent 2.2', 1431): natural gas, production NO, at long-distance pipeline
+    ('ecoinvent 2.2', 1432): natural gas, production RU, at long-distance pipeline
+
+    In [10]: q = Query(Filter("unit", "iis", "tkm"), Filter("name", "in", "lorry"))
+    In [11]: r = q(ei.load())
+    In [12]: len(r)
+    Out[12]: 19
+
+Filter
+======
+
+.. autoclass:: brightway2.Filter
+    :members:
+
+Query
+=====
+
+.. autoclass:: brightway2.Query
+    :members:
+
+Result
+======
 
 .. autoclass:: brightway2.Result
 	:members:
-
-.. autoclass:: brightway2.Query
-	:members:
-
-.. autoclass:: brightway2.Filter
-	:members:

docs/technical.rst

 Documentation
 =============
 
-Documentation is uses `Sphinx <http://sphinx.pocoo.org/>`_ to build the source files into other forms. Building is as simple as changing to the docs directory, and running ``make.bat html`` in Windows and ``make html`` in OS X and Linux.
+Documentation is uses `Sphinx <http://sphinx.pocoo.org/>`_ to build the source files into other forms. Building is as simple as changing to the docs directory, and running ``make.bat html`` in Windows and ``make html`` in OS X and Linux.
+
+Database
+========
+
+.. autoclass:: brightway2.Database
+    :members:
+
+Method
+======
+
+.. autoclass:: brightway2.Method
+    :members:
+
+Import and Export
+=================
+
+.. autoclass:: brightway2.io.EcospoldImporter
+    :members:
+
+.. autoclass:: brightway2.io.EcospoldImpactAssessmentImporter
+    :members:
+Usage
+=====
+
+Brightway2 is now installed, and there are three ways to access the various parts of the framework.
+
+Web interface
+-------------
+
+The web user interface can be started by running:
+
+.. pull-quote::
+    
+    bw2-web.py
+
+Running the web interface for the first time will also give you instructions on setting up databases and making LCA calculations.