Commits

Chris Mutel  committed d4ef649

0.9.0-alpha. Docs almost completely rewritten.

  • Participants
  • Parent commits 91b92a5

Comments (0)

Files changed (17)

-Copyright (c) 2012, Chris Mutel and ETH Zürich
+Copyright (c) 2013, Chris Mutel and ETH Zürich
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
 
-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-Neither the name of ETH Zürich nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Redistributions of source code must retain the above copyright notice, this 
+list of conditions and the following disclaimer. Redistributions in binary 
+form must reproduce the above copyright notice, this list of conditions and the 
+following disclaimer in the documentation and/or other materials provided 
+with the distribution.
+Neither the name of ETH Zürich nor the names of its contributors may be used 
+to endorse or promote products derived from this software without specific 
+prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

File README

-==========================================
-Brightway2 life cycle assessment framework
-==========================================
-
-Brightway2 is a framework for advanced life cycle assessment calculations. It consists of several components which each accomplish specific tasks. This package is a container for all the separate components, for ease of documentation and installation.
-
-Brightway2 is inspired by the Brightway software, which was developed during Chris Mutel's PhD work at ETH Zurich, but is a complete rewrite focusing on simplicity, power, and ease of use. Brightway2 can run on all major operating systems.
-
-Learn more at the following sites:
-
-* http://brightwaylca.org
-* http://chris.mutel.org
-
-Online documentation is at:
-
-* https://brightway2.readthedocs.org/
+Brightway2 life cycle assessment framework
+==========================================
+
+Brightway2 is a framework for advanced life cycle assessment calculations. It consists of several components which each accomplish specific tasks. This package is a container for all the separate components, for ease of documentation and installation.
+
+Brightway2 is inspired by the Brightway software, which was developed during Chris Mutel's PhD work at ETH Zurich, but is a complete rewrite focusing on simplicity, power, and ease of use. Brightway2 can run on all major operating systems.
+
+Official site:
+
+* http://brightwaylca.org
+
+Online documentation:
+
+* https://brightway2.readthedocs.org/
+
+Development blog:
+
+* http://chris.mutel.org
+
+Packages:
+
+* brightway2-data: https://bitbucket.org/cmutel/brightway2-data
+* brightway2-calc: https://bitbucket.org/cmutel/brightway2-calc
+* brightway2-analyzer: https://bitbucket.org/cmutel/brightway2-analyzer
+* brightway2-ui: https://bitbucket.org/cmutel/brightway2-ui
+* brightway2-web-reports: https://bitbucket.org/cmutel/brightway2-web-reports

File docs/conf.py

 
 # General information about the project.
 project = u'Brightway2'
-copyright = u'2012, Chris Mutel'
+copyright = u'2013, Chris Mutel'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.8'
+version = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.1'
+release = '0.9.0-alpha'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

File docs/contributing.rst

+Contributing to Brightway2
+**************************
+
+.. note::
+    See also :ref:`contact-developers` for information on the mailing list.
+
+Brightway2 is designed to be easy to use and develop for. The modular structure of Brightway2 means that you don't have to learn everything at once - pick the subject that best suits your interests and skills, download the code, and start hacking!
+
+Getting started with Python
+===========================
+
+Learning to program is hard - luckily, Python is a great language for beginners. Here are some good beginning resources:
+
+* `How to think like a computer scientist - Think Python <http://www.greenteapress.com/thinkpython/>`_
+* `Software carpentry <http://software-carpentry.org/4_0/python/index.html>`_
+* `Python the hard way <http://learnpythonthehardway.org/>`_
+* `Python scientific lectures <http://scipy-lectures.github.com/index.html>`_
+* `Google's Python class <https://developers.google.com/edu/python/>`_
+
+Required packages
+=================
+
+In addition to the Brightway2 modules you want to work on, you should also install the following:
+
+    * `nose <https://github.com/nose-devs/nose>`_: A library for finding and running tests.
+    * `sphinx <http://sphinx-doc.org/>`_: A library for writing and formatting documentation.
+    * `mercurial <http://mercurial.selenic.com/>`_: A distributed version control system.
+
+This can be done easily:
+
+.. code-block:: bash
+
+    pip install nose sphinx mercurial
+
+Using mercurial
+---------------
+
+Mercurial is a distributed version control system, which records changes made in your source code over time, and allows changes from multiple people to merged to a single code base. `hginit <http://hginit.com/>`_ is a good guide to get started with Mercurial.
+
+Contributing changes to Brightway2
+----------------------------------
+
+The preferred way to submit changes is with a pull request on Bitbucket. See the `pull request docs <http://blog.bitbucket.org/2011/06/17/pull-request-revamp/>`_ for an illustrated examples. Pull requests which add code would ideally also include documentation and tests.
+
+No Python needed - making graphics better
+=========================================
+
+One easy way of helping out that doesn't require any knowledge of Python, matrices, or even actually life cycle assessment at all, is to help make the existing graphics better or introduce new ones. Each graphic in the LCA report is also available in a online:
+
+* `Treemap <http://tributary.io/inlet/4951698>`_
+* `Hinton matrix <http://tributary.io/inlet/4951859>`_
+* `Force-directed graph`_
+* `Monte Carlo results <http://tributary.io/inlet/4951873>`_
+
+The code here is editable, and the changes you make will be immediately reflected in the display. Feel free to make some tweaks, or even major changes, to make the visualizations nicer, easier to understand, and simpler. If you have for other graphics that would be useful in interpreting LCA results, or in exploring inventory datasets or impact assessment methods, feel free to :ref:`contact-developers` to get a smaple dataset.
+
+Making the backend better
+=========================
+
+There are plenty of big and small things that can be done to improve all aspects of the Brightway2 calculation routines and and data management.
+
+Principles for good code
+------------------------
+
+    * Follow the Zen of Python - if you don't know what this is, try typing ``import this`` in a python shell.
+    * Follow style guides like `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_. Tools like `pylint <http://pypi.python.org/pypi/pylint>`_ can help.
+    * Write tests, and check test coverage.
+    * Use `sphinx <http://sphinx-doc.org/>`_ to write documentation while you are writing code.
+
+Easy problems
+=============
+
+Tune the force-directed graph parameters to avoid the "hairball" problem
+------------------------------------------------------------------------
+
+There are a number of parameters in the `Force-directed graph`_, such as link distance and circle radius, which can be tuned to make the graph easier to understand. Go ahead and try to change them a bit and see what happens!
+
+Implement other graphs from D3.js
+---------------------------------
+
+Here are some possibilities we could include in either LCA reports, or in exploring or analyzing inventory databases:
+
+    * Database visualization
+        * `Hive plots <http://bost.ocks.org/mike/hive/>`_
+        * `Hierarchal edge modelling <http://mbostock.github.com/d3/talk/20111116/bundle.html>`_
+        * `Sunburst partition <http://bl.ocks.org/4063423>`_
+        * `Chord diagrams <http://bl.ocks.org/4062006>`_
+    * Supply chain visualization
+        * `Collapsible force-directed <http://mbostock.github.com/d3/talk/20111116/force-collapsible.html>`_
+        * `Rheingold-Tilford tree <http://bl.ocks.org/4063550>`_
+    * Other results visualization
+        * `Circle packing <http://bl.ocks.org/4063530>`_
+        * `Bubble chart <http://bl.ocks.org/4063269>`_
+
+Improve report layout and CSS
+-----------------------------
+
+Those who know a bit about design, or at least think that they do, are welcome to make the report page better. Here is an `example report page <http://reports.brightwaylca.org/report/fb20439529cb414784e25acb8b3ef426>`_.
+
+Improve test coverage
+---------------------
+
+Each of the three calculational packages has an `online report available <http://coverage.brightwaylca.org/>`_. Many of the test coverage failures can be easily resolved with simple tests, and writing simple tests is a great way to get started with Python and Brightway2.
+
+Medium problems
+===============
+
+Find holes in tests
+-------------------
+
+Tests always have edge cases that weren't anticipated by the developers, and coverage doesn't test for exceptions. Finding these edge cases or exceptions is a thankless but extremely important part of making robust software.
+
+Rewrite main LCA class in a more functional style
+-------------------------------------------------
+
+The current LCA class uses ``self`` attributes extensively to store data during the calculation. A move to a more functional style, where inputs are explicitly passed, and outputs returned, would make the tests more robust and independent. It would also make it easier to write LCA subclasses. So, for example, move from this code:
+
+.. code-block:: python
+
+    def solve_linear_system(self):
+        if hasattr(self, "solver"):
+            return self.solver(self.demand_array.data)
+        else:
+            return spsolve(
+                self.technosphere_matrix.data,
+                self.demand_array.data)
+
+To this:
+
+.. code-block:: python
+
+    def solve_linear_system(self, demand, technosphere, solver=None):
+        if solver is not None:
+            return solver(demand.data)
+        else:
+            return spsolve(technosphere.data, demand.data)
+
+Add the Gini coefficient test of LCA result inequality
+------------------------------------------------------
+
+LCA inequality tests are a measure of how much an individual LCA score is determined by just a few LCI datasets, and as such is important for measuring data quality and result robustness. The `concentration index <http://en.wikipedia.org/wiki/Concentration_ratio>`_ and the `Herfindahl index <http://en.wikipedia.org/wiki/Herfindahl_index>`_ are already included in ``bw2analyzer.contribution.ContributionAnalysis``, but the `Gini coefficient <http://en.wikipedia.org/wiki/Gini_coefficient>`_, which is more widely known would be nice to have as well.
+
+Ecospold exporter
+-----------------
+
+The base Brightway2 data format doesn't include fields for all of the Ecospold data format, but we can still export that data that is available in the Ecospold format. This would help in making Brightway2 data more tranportable. It is not necessarily a dificult task, but writing a lot of XML processing code is never very much fun.
+
+Dataset process adder & editor
+------------------------------
+
+Because the actual data stored in a Brightway2 inventory dataset is relatively simple, it should be possible to create a couple of simple forms for adding and editing new datasets. The only difficulty is in making a usable user interface; so, for example, it should be easy to link new technosphere or biosphere inputs, with some autcompletion or other easy searching.
+
+Hard problems
+=============
+
+Database browser
+----------------
+
+The standard way to explore inventory databases is with a category tree, and it would be helpful to have somethng like that, but one can also think of exploring a database by mass type, name, location, or other types of faceting. It would probably be advisable to include some nice visualizations with D3, as this is relatively simply done, and can add a great deal of usability for end users.
+
+LCIA method browser
+-------------------
+
+Similarly, we would also like to be able to browse and edit impact assessment methods, looking at names, types of emissions and resource consumptions, and categories.
+
+Sankey flow diagram
+-------------------
+
+Sankey diagrams are helpful for showing the flows of raw material inputs or environmental impact through the supply chain. There are some `initial ideas <http://blog.bitjuice.com.au/2013/02/using-d3-js-to-visualise-hierarchical-classification/>`_ , see also `a simpler example <http://bost.ocks.org/mike/sankey/>`_ on how to do this in D3, but the problem here is actually twofold:
+
+    #. Disaggregating the supply chain graph in a reasonable fashion without having it either collapse or retain too many deep links
+    #. Graph layout and display of additional information in D3
+
+.. _Force-directed graph: http://tributary.io/inlet/4681149

File docs/credits.rst

+Credits
+*******
+
+Authors
+=======
+
+* Chris Mutel
+
+.. _contact-developers:
+
+Contact the developers
+======================
+
+Brightway2 has a mailing list: brightway2@googlegroups.com. You can register at the `Google groups site <https://groups.google.com/forum/?fromgroups#!forum/brightway2>`_.
+
+You can also email Chris directly at cmutel@gmail.com.
+
+License
+=======
+
+Brightway2 is licensed under the `BSD license <http://opensource.org/licenses/BSD-3-Clause>`_.
+
+::
+
+    Copyright (c) 2013, Chris Mutel and ETH Zürich
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer. Redistributions in binary
+    form must reproduce the above copyright notice, this list of conditions and the
+    following disclaimer in the documentation and/or other materials provided
+    with the distribution.
+    Neither the name of ETH Zürich nor the names of its contributors may be used
+    to endorse or promote products derived from this software without specific
+    prior written permission.
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

File docs/current_status.rst

-Current package staus
-*********************
-
-brightway2-data
-===============
-
-Current version: **0.8.3**
-
-Upcoming features and releases
-------------------------------
-
-* Export and import from other Brightway2 instances (with JSON?)
-* Import SimaPro and other broken Ecospold files
-* Comprehensive documentation 
-* Comprehensive tests (including coverage)
-
-brightway2-calc
-===============
-
-Current version: **0.8.1**
-
-Upcoming features and releases
-------------------------------
-
-* Re-write LCA class in a more functional style (less self.* attributes passed to methods)
-* Comprehensive documentation 
-* Comprehensive tests (including coverage)
-
-brightway2-analyzer
-===================
-
-Current version: **0.1.1**
-
-Upcoming features and releases
-------------------------------
-
-* Comprehensive documentation 
-* Comprehensive tests (including coverage)
-* Add Gini coefficient
-* Add database explorer
-
-brightway2-ui
-=============
-
-Current version: **0.4.5.1**
-
-Upcoming features and releases
-------------------------------
-
-* Comprehensive documentation 
-* Comprehensive tests (including coverage)
-* Bring CLI to parity with web interface (where applicable)
-* Add database explorer
-* Add method explorer
-* Continue cleanup of LCA results page

File docs/images/new-graphics.png

Removed
Old image

File docs/index.rst

 Brightway2 life cycle assessment framework
 ==========================================
 
-Brightway2 is a simple framework for life cycle assessment (LCA). Its focus is on efficient calculation and visualization. Brightway2 is a complete rewrite of the original Brightway, which was a previous LCA framework developed during the PhD thesis of Chris Mutel.
+Brightway2 is a new framework for life cycle assessment (LCA). Its focus is on efficient calculation and visualization.
 
-.. warning:: Brightway2 is in heavy development, and while it is used by mutiple people every day, it is probably not ready for people who don't like digging into source code and filing bug reports.
+Please see `the main Brightway2 site <http://brightwaylca.org>`_ for an introduction.
 
-Why another LCA framework?
-==========================
-
-Because existing LCA software is not very good at calculations. Brightway2 is not trying to replace software such as OpenLCA or SimaPro; rather, it is designed for individual analysts to be able to do cutting edge calculations on their computers, their servers, or in the cloud.
-
-Features
-========
-
-Fast LCA and Monte Carlo calculations
--------------------------------------
-
-The life cycle assessment calculators are the most advanced part of Brightway2. For those that are interested, a full technical guide is available. For the rest of you, suffice it to say that LCA calculations are powerful and efficient (working with LCI databases of hundreds of thousands of processes has been done successfully), and the Monte Carlo implementation allows for effective use of modern computers. On a semi-modern laptop, around 100 Monte Carlo iterations per core are possible, and each core can be used in parallel.
-
-New data visualizations
------------------------
-
-.. image:: images/new-graphics.png
-    :align: center
-
-Treemaps and Hinton matrices are already part of the standard LCA report, and new visualizations using the D3 library are planned.
-
-Simple data handling
---------------------
-
-Brightway2 uses a very simple data structure. Instead of a database, which is powerful but difficult to install or upgrade, Brightway2 uses a data directory, and saves data as Python datastructures serialized to normal files. The location of the data directory can be configured; default is in your home directory. Although this approach loses some of the benefits of relational databases, it has several advantages:
-
-* No database installation or configuration.
-* You can easily share your work with someone else by copying the data directory and sending it to your colleagues. Syncing services like dropbox can also be easily used.
-* Copying, modifying, and backing up databases is easy and fast.
-
-Quick start
-===========
-
-This is the easiest way to get started using Brightway2 on **Windows**. If you are interested in using the full power of the Brightway2 framework, or are using **Mac OS X** or **Linux**, see other installation options:
-
-* :ref:`windows-install`
-* :ref:`os-x-install`
-* :ref:`linux-install`
-
-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>`_
-
-.. note:: Be sure to check the option to install **pip**:
-
-.. image:: images/python-xy-pip.png
-    :align: center
-
-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 -> Command Prompt), and type in the following:
-
-.. code-block:: bash
-	
-	pip install brightway2
-
-Finally, again in the command prompt, start Brightway2:
-
-.. code-block:: bash
-
-	bw2-web.py
-
-This should start the program, and open a new web browser tab to the correct address. Brightway2 will recognize that you are starting Brightway2 for the first time, and give you instructions on how to download basic data, import your projects, and start working.
+.. note::
+    Brightway2 is currently only compatible with python 2.7, not python 3. Brightway2 will remain 2.7 only until `flask <http://pypi.python.org/pypi/Flask>`_ and its dependencies are ported to Python 3.
 
 Documentation
 =============
 .. toctree::
    :maxdepth: 2
 
+   quickstart
    installation
-   introduction
-   usage
-   current_status
+   tutorials
+   key-concepts
+   contributing
+   packages
+   credits
 
 Indices and tables
 ==================

File docs/installation.rst

 
 .. _windows-install:
 
-Windows 
+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>`_. Using `Anaconda Community Edition <http://continuum.io/anacondace.html>`_, or the `Enthought Python Distribution <http://www.enthought.com/products/epd.php>`_ is also possible, but not tested (they have custom package management commands). 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:
 
 .. code-block:: bash
-	
-	pip install bw2all
+
+	pip install brightway2
 
 Developers
 ----------
 If you want to develop with Brightway2, 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
 
 To only work with Brightway2, finish your installation using another Terminal command:
 
 .. code-block:: bash
-	
+
 	sudo pip install brightway2
 
 Developers
 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 fuzzywuzzy
 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
-    
+
     mkvirtualenv bw2 --system-site-packages
     pip install docopt voluptuous bw-stats-toolkit flask requests fuzzywuzzy
     pip install -e hg+https://bitbucket.org/cmutel/brightway2-data#egg=bw2data
 Second, install the Brightway2 metapackage:
 
 .. code-block:: bash
-    
+
     pip install brightay2
 
 If you want to install packages manually, or not install everything, Brightway2 uses the following Python packages:
 
-* progressbar 
+* progressbar
 * flask
 * docopt
 * fuzzywuzzy

File docs/introduction.rst

-Introduction
-************
-
-Brightway2 has the following features:
-
-* Foo
-* Bar

File docs/key-concepts.rst

+Key concepts
+************
+
+The data directory
+==================
+
+All Brightway2 data is stored in a data directory, but the location of the directory can be chosen by the user. The data directory is just a bunch of subdirectories and files, so it is safe for backup programs or sync services like Dropbox.
+
+Structure
+---------
+
+::
+
+    data directory
+        files:
+            databases.json ---- Metadata about LCI databases
+            geomapping.pickle - Listing of all locations in all databases and methods
+            mapping.pickle ---- Listing of all activities in all LCI databases
+            methods.json ------ Metdata about LCIA methods
+            preference.json --- User settings
+        subdirectories:
+            backups ----------- Directory for LCI database backups
+            intermediate ------ Directory where LCI database and LCIA method documents are stored
+            logs -------------- Logs of Brightway2 activity
+            processed --------- Compressed numerical arrays made from LCI and LCIA documents
+            reports ----------- Data from LCA calculations
+
+Data directory location
+-----------------------
+
+.. note::
+    You can ignore all these technical details if you create a file called ``brightway2`` in your home directory, and don't want to do anything fancy.
+
+The user can specify the ``data directory`` location in any of three different ways. In all cases, the directory should already exist. The first thing that Brightway will look for is the `environment variable <http://foo.bar>`_ ``BRIGHTWAY2_DIR``. If this is found, then it is the location of the ``data directory``. An environment variable is especially convenient if you have multiple copies of Brightway2 installed on one machine, or if you want to keep separate workspaces for different projects.
+
+To set an environment variable:
+
+    * Unix/Mac: ``export BRIGHTWAY2_DIR=/path/to/brightway2/directory``. Add this to your ``.profile`` or similar file to have this set each time you open a terminal window.
+    * Windows 7: Use ``setx BRIGHTWAY2_DIR=\path\to\brightway2\directory`` to set an environment variable permanently.
+
+The second thing that Brightway2 will try is a file called ``.brightway2path`` in your home directory. If this file is present, it should have one line, which is the directory location. No quoting or special characters are needed.
+
+Because it can be difficult to work with so-called "dot-files", whose name starts with a ``.``, Brightway2 will also try to read a file call ``brightway2path.txt`` in your home directory. This works the same as the ``.brightway2path`` file.
+
+Finally, Brightway2 will try to see if there is a writeable directory in your home directory called ``brightway2``.
+
+If none of these attempts succeed, Brightway2 will work in a temporary directory, but will complain about it, as these directories can be deleted by the operating system.
+
+Databases
+=========
+
+In Brightway2, a ``database`` is the term used to organize a set of activity datasets. Databases can be big, like ecoinvent, or as small as one dataset. You can have as many databases as you like, and databases can link into other databases. You can also have two databases that each depend on each other.
+
+.. _biosphere-database:
+
+Biosphere database
+------------------
+
+When Brightway2 is set up, it downloads and installs a special ``biosphere`` database. This database has all the resource and emission flows from the ecoinvent database, and is the database that imported life cycle impact assessment methods will link to.
+
+You can define biosphere flows - resources and emissions - in any database you like, but it is probably best to use the pre-defined flows in the ``biosphere`` database whenever you can. If you need to add some custom flows, feel free to create a separate new database.
+
+Documents
+---------
+
+An activity dataset is a document - just some text, with a minial amount of formatting. For example, here is a Brightway2 activity dataset from the US LCI:
+
+.. code-block:: python
+
+    {'categories': ['biomass', 'fuels'],
+     'exchanges': [{'amount': 11968.25,
+       'code': 7,
+       'comment': 'From gasoline',
+       'group': 2,
+       'input': ('biosphere', '6d336c64e3a0ff08dee166a1dfdf0946'),
+       'type': 'biosphere',
+       'uncertainty type': 0}],
+     'location': 'RNA',
+     'name': 'Energy, output',
+     'type': 'process',
+     'unit': 'megajoule'}
+
+There are some elements which might seem mysterious, and some elements which just make sense. I hope that things like ``name`` and ``unit`` don't need any explanation. The list of ``exchanges`` might be a bit more difficult to understand at first, because there are some weird fields like ``code`` and ``group`` which are left over from the import process. Actually, the list of required fields is quite small.
+
+.. note::
+    The details of the data format are described in :ref:`database-documents`
+
+Here are the important points about activity datasets being documents:
+
+    * They are a section of human-readable data that you can manipulate manually in a text editor, or change en masse programmatically.
+    * Because they can be exported as text, and in a format that is accessible to almost every computer language (`JSON <http://www.json.org/>`_), activity datasets can be easily exported and used by other programs without spending hour messing around with XML which is constructed slightly differently by each LCA program.
+    * Activity datasets have a small number of required fields, but allow any additional information you would like to add, so that it is easy to add whatever custom data you need for your application. #TODO: Examples
+
+.. _dataset-codes:
+
+Dataset codes
+-------------
+
+Linking activity datasets within and between databases requires a way to uniquely identify each dataset. Brightway uses the idea that each dataset has a unique code. A code can be a number, like ``1``, or a string of numbers and letters, like ``swiss ch33se``. When you create datasets manually, you will need to assign each dataset a code. When you import a database, the codes will be automatically generated for you.
+
+Activity hashes
+---------------
+
+When you import an *ecospold* dataset, the codes that are generated automatically look like a bunch of nonsense, like this: ``6d336c64e3a0ff08dee166a1dfdf0946``. Although the *ecospold* format does include numbers, and some producers of ecoinvent use those numbers in a meaningful way, every other program that produces *ecospold* messes the numbers up, and so we can't believe them.
+
+We want to have a way of identifying datasets which is consistent from machine to machine, so that it is easier to share and work with datasets without have to relink activities. The way Brightways identifies an activity or flow is with the `MD5 <http://en.wikipedia.org/wiki/MD5>`_ hash of a few attributes: the ``name``, ``location``, ``unit``, and ``categories``. The function is ``bw2data.utils.activity_hash``, but the procedure is simple: concatenate the name, each category, the unit and the location, all as lower-case strings. If an attribute doesn't have a value, ignore it. Then take the `MD5 <http://en.wikipedia.org/wiki/MD5>`_ hash of the resulting string.
+
+Exchanges
+---------
+
+Exchanges are a list of the inputs and outputs of an activity. For example an activity might consume some resources, emit some emissions, and have other technoligcal goods as emissions. Each activity also has at least one technological output.
+
+Each exchange has a ``type``, which indicates where the exchange goes to or comes from. The predefined types are as follows:
+
+    * ``production``: How much of the main output is produced by this dataset. A ``production`` exchange is not required, and when absent, a default value of 1 is used.
+    * ``technosphere``: An input of a technological flow.
+    * ``biosphere``: A consumption of a resource, or an emission to the environment. These flows are normally from the :ref:`biosphere-database`.
+
+Brightway2 cannot, by itself, directly handle multi-output activities. However, you can include multi-output activites with substitution (see #TODO), and the **ecospold** importer will allocate multi-output datasets. This lack of support for multi-output datasets is due to Brightway2 being centered on matrix-calculations, which require a square technosphere matrix. If each dataset did not have precisely one output, the technosphere matrix would be rectangular, and therefore not generally solvable.
+
+Impact assessment methods
+=========================
+
+In Brightway2, each impact assessment method is a set of characterization factors for a set of biosphere flows. Each impact category and subcategory is a separate method, and each method is stored and calculated separately.
+
+Methods are identified by a list of names, which could be as simple as:
+
+.. code-block:: python
+
+    ("my new cool method for ice cream",)
+
+which is probably most applicable for those who are particularly concerned with ice cream resource depletion; a more typical example is:
+
+.. code-block:: python
+
+    (u'ecological scarcity 1997', u'total', u'total')
+
+Impact assessment method names can have any length and number of qualifiers, but must always be a list of strings.
+
+.. warning::
+    For technical reasons, impact assessment names must be stored as a `tuple <http://docs.python.org/2/tutorial/datastructures.html#tuples-and-sequences>`_, not a `list <http://docs.python.org/2/tutorial/introduction.html#lists>`_, i.e. they must have ``()`` at the beginning and end, and not ``[]``.
+
+Data formats
+============
+
+Pickle is the default data storage format
+-----------------------------------------
+
+Why is the Python standard library module `pickle <http://docs.python.org/2/library/pickle.html>`_ as the local data storage format?
+
+The ``pickle`` module is fast, portable, and built-in. While using compression (such as gzip and bzip2) would reduce the size of the saved files, it also dramatically increases loading and saving times, by a factor of 3 - 30, depending on the test. Overall, the speed of ``pickle`` `seems to be fine <http://kbyanc.blogspot.ch/2007/07/python-serializer-benchmarks.html>`_.
+
+The ``marshal`` module is faster - 40% faster writing, 25% faster reading - but produces files twice as big, and can change from computer to computer or even when Python is upgraded. The costs and potential risks of ``marshal`` overwhelm its speed gains.
+
+Unlike ``JSON``, ``pickle`` can save all Python objects, and is consistently faster when considering all target operating systems. Moreover, ``pickle`` is part of the standard library, so no additional installation is necessary. There does not appear to be one standard ``JSON`` library, see e.g. `anyjson <http://pypi.python.org/pypi/anyjson/>`_, `yajl <http://pypi.python.org/pypi/yajl>`_, and `ujson <http://pypi.python.org/pypi/ujson/>`_, in addition to the builtin.
+
+Some metadata is serialized to JSON
+-----------------------------------
+
+`JSON <http://www.json.org/>`_ is a great format for data interchange, and for humans to edit. Some metadata, such as the LCI databases and LCIA methods installed, and user preferences, are stored in JSON. These are files that humans might want to change manually, so it makes sense for them to be easy to edit. These files are also relatively small, and could be accessed by other programming languages.
+
+Database metadata
+-----------------
+
+There is a very basic set of metadata stored about each inventory database, stored in the file ``databases.json``. To get the metadata about a database, do something like the following:
+
+.. code-block:: python
+
+    from brightway2 import *
+    databases["ecoinvent 2.2"]
+
+.. note::
+    See also the `databases manager documentation <http://bw2data.readthedocs.org/en/latest/technical.html#bw2data.meta.Databases>`_
+
+The returned metadata is:
+
+.. code-block:: python
+
+    {u'depends': [u'biosphere'],
+     u'from format': [u'Ecospold', 1],
+     u'number': 4087,
+     u'version': 1}
+
+Databases have the following metadata:
+
+    * *depends*: A list of database names that this database links into and depends upon.
+    * *from format*: The format this database was imported from. Can be a string or a list.
+    * *number*: Number of inventory datasets.
+    * *version*: The integer version number of this database. Each time a database is saved this number is automatically incremented.
+
+.. _database-documents:
+
+Database documents
+------------------
+
+A database consists of inventory datasets, and inventory datasets have a required form and a number of required fields. However, these requirements form a minimum needed for LCA calculations - you can always add extra fields as needed by your application.
+
+Here is a selection from an example dataset from the US LCI:
+
+.. code-block:: python
+
+    {'categories': ['Wood Product Manufacturing',
+      'Softwood Veneer and Plywood Mnf.'],
+     'code': 1,
+     'exchanges': [{'amount': 1.0,
+       'code': 6,
+       'group': 2,
+       'input': ('US LCI', u'6ddb4cc00f9e42aa48515248256c31dc'),
+       'type': 'production',
+       'uncertainty type': 0},
+      {'amount': 7.349999999999999e-06,
+       'code': 5,
+       'group': 4,
+       'input': ('biosphere', u'51447e58e03a40a2bbd9abf45214b7d3'),
+       'type': 'biosphere',
+       'uncertainty type': 0}],
+     'location': 'RNA',
+     'name': 'Green veneer, at plywood plant, US PNW',
+     'type': 'process',
+     'unit': u'kilogram'}
+
+The document structure is:
+
+    * *categories* (list of strings, optional): A list of categories and subcategories. Can have any length.
+    * *code* (string or number, optional): An identifier from the imported database, if available.
+    * *exchanges* (list): A list of activity inputs and outputs, with its own schema.
+        * *amount* (float): Amount of this exchange.
+        * *uncertainty type* (integer): Integer code for uncertainty distribution of this exchange, see :ref:`uncertainty-type` for more information.
+        * *type* (string): One of ``production``, ``technosphere``, and ``biosphere``.
+            * ``production`` is an exchange that describes how much this activity produces. A ``production`` exchange is not required - the default value is 1.
+            * ``technosphere`` is an input of a technosphere flow from another activity dataset.
+            * ``biosphere`` is a resource consumption or emission to the environment.
+        * *input* (database name, database code): The technological activity that is linked to, e.g. ``("my new database", "production of ice cream")`` or ``('biosphere', '51447e58e03a40a2bbd9abf45214b7d3')``. See also :ref:`dataset-codes`.
+        * *comment* (string, optional): A comment on this exchange. Used to store pedigree matrix data in ecoinvent v2.
+        * *code*: (string or number, optional): An identifier from the imported database, if available.
+        * *maximum* (float, optional): A statistical parameter whose meaning depends on the :ref:`uncertainty-type`.
+        * *miniumum* (float, optional): A statistical parameter whose meaning depends on the :ref:`uncertainty-type`.
+        * *sigma* (float, optional): A statistical parameter whose meaning depends on the :ref:`uncertainty-type`.
+    * *location* (string, optional): A location identifier. Default is *GLO*.
+    * *name* (string): Name of this activity.
+    * *type* (string): One of ``process``, ``emission``, or ``resource``, but you can add custom types. Not needed for calculations; intended for data processing.
+    * *unit* (string): Unit of this activity. Units are normalized when written to disk.
+
+.. note::
+    Technological ``exchanges`` are a list of **inputs**.
+
+.. note::
+    There should be a maximum of **one** ``production`` exchange.
+
+.. note::
+    Database documents can be validated with ``bw2data.validate.db_validator(my_data)``, or ``Database("my database name").validate(my_data)``.
+
+.. _uncertainty-type:
+
+Uncertainty types
+-----------------
+
+.. note::
+    All distributions (where it is applicable) can be bounded, i.e. you can specify and minimum and maximum value in addition to other parameters. This can be helpful in ensuring, for example, that distributions are always postive.
+
+The integer *uncertainty type* fields are defined in a separate software package called `bw-stats-toolkit <https://bitbucket.org/cmutel/bw-stats-toolkit>`_. The uncertainty types are:
+
+    * ``0``: Undefined uncertainty. Does not vary.
+    * ``1``: No uncertainty. Does not vary.
+    * ``2``: Lognormal distribution. This is **purposely** handled in an inconsistent fashion, unfortunately. The ``amount`` field is the median of the data, and the ``sigma`` field is the standard deviation of the data **when it is log-transformed**, i.e. the σ from the formula for the log-normal PDF.
+    * ``3``: Normal distribution. ``amount`` is the mean, and ``sigma`` is the standard deviation.
+    * ``4``: Uniform distribution. Picks values between ``minimum`` and ``maximum``.
+    * ``5``: Triangular distribution. Picks values between ``minimum`` and ``maximum``, with a mode of ``amount``.
+    * ``6``: Bernoulli distribution. ``amount`` is the cutoff between yes and no. ``maximum`` and ``minimum`` can rescale the interval away from (0, 1).
+    * ``7``: `Discrete uniform <http://en.wikipedia.org/wiki/Uniform_distribution_(discrete)>`_ distribution picks integer values between ``minimum`` and ``maximum``.
+    * ``10``: Beta distribution. ``amount`` is α, and ``sigma`` is β. ``maximum`` is a scaling parameter.
+
+LCIA method metadata
+--------------------
+
+There is a very basic set of metadata stored about each model, stored in the file ``methods.json``. To get the metadata about a method, do something like the following:
+
+.. code-block:: python
+
+    from brightway2 import *
+    methods[(u'ecological scarcity 1997', u'total', u'total')]
+
+.. note::
+    See also the `methods manager documentation <http://bw2data.readthedocs.org/en/latest/technical.html#bw2data.meta.Methods>`_
+
+The returned metadata is:
+
+.. code-block:: python
+
+    {u'abbreviation': u'ecologicals1997tt-UHk4Z8Pr',
+     u'description': u'Swiss method',
+     u'num_cfs': 1249,
+     u'unit': u'UBP'}
+
+Methods have the following metadata:
+
+    * *abbreviation*: Becuase LCIA methods have long and complicated names, Brightway2 abbreviates them to get a safe filename to save the data.
+    * *description*: A description of this method or submethod.
+    * *num_cfs*: Number of characterization factors.
+    * *unit*: The unit of this method or submethod.
+
+LCIA method documents
+---------------------
+
+The impact assessment method documents are quite simple - indeed, it is a bit of a stretch to call them documents at all. Instead, they are a list of biosphere flow references, characterization factors, and locations. All LCIA methods in Brightway2 are regionalized, though the default installed methods only provide global characterization factors. Here is a simple example:
+
+.. code-block:: python
+
+    from brightway2 import *
+    Method((u'ecological scarcity 1997', u'total', u'total')).load()[:5]
+
+This returns the following:
+
+.. code-block:: python
+
+    [[(u'biosphere', u'21c70338ff2e1cdc8e468f4c90f113a1'), 32000, u'GLO'],
+     [(u'biosphere', u'86a37cf9e44593f1c41fdce53de27715'), 32000, u'GLO'],
+     [(u'biosphere', u'a8cc9c61aa343fa01532bb16cec7f90d'), 32000, u'GLO'],
+     [(u'biosphere', u'b0a29177e77471a49b5a7d6a88212bf8'), 32000, u'GLO'],
+     [(u'biosphere', u'72c1cf2fee31a2cb6cdc39abda29a0df'), 32000, u'GLO']]
+
+Each list elements has three components.
+    #. A reference to a biosphere flow, e.g. ``(u'biosphere', u'21c70338ff2e1cdc8e468f4c90f113a1')``.
+    #. The numeric characterization factor.
+    #. A location, which is used because Brightway2 will soon gain the ability to do regionalized LCA.
+
+The current format does not include fields for characterizing the uncertainty of the characterization factors, but the processed characterization matrices do, and it is anticipated that this functionality will be added relatively soon.
+
+.. note::
+    LCIA method documents can be validated with ``bw2data.validate.ia_validator(my_data)``, or ``Method(("my", "method", "name")).validate(my_data)``.
+
+Intermediate and processed data
+-------------------------------
+
+Both inventory datasets and impact assessment methods are stored as structured text files, but these files are not efficient when constructing the technosphere, biosphere, and characterization matrices. These text documents are stored in the ``intermediate`` folder. Brightway2 also has a ``processed`` folder, which stores only the data needed to construct the various computational matrices. These data are stored as `numpy structured arrays <http://docs.scipy.org/doc/numpy/user/basics.rec.html>`_.
+
+For both databases and LCIA methods, the method ``.write(some_data)`` will write an *intermediate* data file, while the subsequent method ``.process()`` will transform the intermediate data file to an array. These two functions are intentionally separate, as it is sometimes desirable to do one and not the other.
+
+.. warning::
+    Every time you save a new version of an inventory database or an impact assessment method, e.g. with ``my_database.write(my_data)``, be sure to also call ``my_database.process()``, or your changes will not be used in LCA calculations.
+
+Reports
+-------
+
+LCA reports calculated with ``bw2analyzer.report.SerializedLCAReport`` are written as a JSON file to disk. It has the following data format:
+
+.. code-block:: python
+
+    {
+        "monte carlo": {
+            "statistics": {
+                "interval": [lower, upper values],
+                "median": median,
+                "mean": mean
+            },
+            "smoothed": [  # This is smoothed values for drawing empirical PDF
+                [x, y],
+            ],
+            "histogram": [  # This are point coordinates for each point when drawing histogram bins
+                [x, y],
+            ]
+        },
+        "score": LCA score,
+        "activity": [
+            [name, amount, unit],
+        ],
+        "contribution": {
+            "hinton": {
+                "xlabels": [
+                    label,
+                ],
+                "ylabels": [
+                    label,
+                ],
+                "total": LCA score,
+                "results": [
+                    [x index, y index, score], # See hinton JS implementation in bw2ui source code
+                ],
+            },
+            "treemap": {
+                "size:" LCA score,
+                "name": "LCA result",
+                "children": [
+                    {
+                    "name": activity name,
+                    "size": activity LCA score
+                    },
+                ]
+            }
+            "herfindahl": herfindahl score,
+            "concentration": concentration score
+        },
+        "method": {
+            "name": method name,
+            "unit": method unit
+        },
+        "metadata": {
+            "version": report data format version number (this is 1),
+            "type": "Brightway2 serialized LCA report",
+            "uuid": the UUID of this report,
+            "online": URL where this report can be accessed. Optional.
+        }
+    }
+
+Data interchange
+----------------
+
+Brightway2 has a format for transferring inventory data between computers. This format is called ``bw2package``, and is an inventory database written to JSON, and then compressed with bzip2. ``bw2package`` is compressed JSON because ``pickle`` is `not a safe data transfer format <http://docs.python.org/2/library/pickle.html>`_, and because JSON is readable by other programs and programming languages. The JSON dataformat is:
+
+.. code-block:: python
+
+    {
+        database name: {
+            "metadata": {
+                "from format": format the data was converted from, e.g. ecospold,
+                "depends": name of databases that this database links into,
+                "number": number of datasets in this database,
+                "version": version number of this database
+            },
+            "data": {
+                code: dataset,
+            }
+        }
+    }
+
+There is a separate format for impact assessment methods, which are stored in a ``bw2iapackage`` file. This is also compressed JSON, and has a similar format:
+
+.. code-block:: python
+
+    [
+        {
+            "metadata": {
+                "name": [list, of, names],
+                "description": description,
+                "num_cfs": number of cfs,
+                "abbreviation": abbreviation of method name,
+                "unit": unit of impact assessment method
+            },
+            "cfs": [
+                {
+                    "database": database name, e.g. biosphere,
+                    "code": code of the biosphere flow,
+                    "location": location where the characterization factor is valid (optional),
+                    "amount": characterization factor amount,
+                    "uncertainty type": integer uncertainty type,
+                    "sigma": uncertainty parameter,
+                    "maximum": uncertainty parameter,
+                    "minimum": uncertainty parameter
+                }
+            ]
+        }
+    ]

File docs/packages.rst

+Brightway2 packages
+*******************
+
+brightway2-data
+===============
+
+This package provides facilities for managing LCI databases and LCIA methods, as well as input and output scripts.
+
+* `source code <https://bitbucket.org/cmutel/brightway2-data>`_
+* `documentation <https://bw2data.readthedocs.org/en/latest/>`_
+* `test coverage <http://coverage.brightwaylca.org/data/index.html>`_
+
+brightway2-calc
+===============
+
+This package provides classes for LCA calculations, both static and uncertain, and basic regionalized LCA.
+
+* `source code <https://bitbucket.org/cmutel/brightway2-calc>`_
+* `documentation <https://brightway2-calc.readthedocs.org/en/latest/>`_
+* `test coverage <http://coverage.brightwaylca.org/calc/index.html>`_
+
+brightway2-analyzer
+===================
+
+This package provides functions for interpreting and analyzing LCI databases, LCIA methods, and LCA results.
+
+* `source code <https://bitbucket.org/cmutel/brightway2-analyzer>`_
+* `documentation <https://bw2analyzer.readthedocs.org/en/latest/>`_
+* `test coverage <http://coverage.brightwaylca.org/analyzer/index.html>`_
+
+brightway2-ui
+=============
+
+This package provides both command line and web user interfaces.
+
+* `source code <https://bitbucket.org/cmutel/brightway2-ui>`_

File docs/quickstart.rst

+Windows quickstart
+******************
+
+This is the easiest way to get started using Brightway2 on **Windows**. If you are interested in using the full power of the Brightway2 framework, or are using **Mac OS X** or **Linux**, see other installation options:
+
+* :ref:`windows-install`
+* :ref:`os-x-install`
+* :ref:`linux-install`
+
+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>`_
+
+.. note:: Be sure to check the option to install **pip**:
+
+.. image:: images/python-xy-pip.png
+    :align: center
+
+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 -> Command Prompt), and type in the following:
+
+.. code-block:: bash
+
+    pip install brightway2
+
+Finally, again in the command prompt, start Brightway2:
+
+.. code-block:: bash
+
+    bw2-web.py
+
+This should start the program, and open a new web browser tab to the correct address. Brightway2 will recognize that you are starting it for the first time, and give you instructions on how to download basic data, import your projects, and start working.

File docs/tutorials.rst

+Tutorials
+*********
+
+Getting started
+===============
+
+<insert online tutorial here>
+
+The command line interface
+==========================
+
+The following commands are available:
+
+    * ``bw2-controller.py list databases``: List all installed databases
+    * ``bw2-controller.py list methods``: List all installed methods
+    * ``bw2-controller.py details <name>``: Give details on inventory database ``<name>``. If the database name has spaces in it, it should be quoted, like this: ``"name with spaces"``.
+    * ``bw2-controller.py copy <name> <newname>``: Copy inventory database ``<name>`` to new name ``<newname>``.
+    * ``bw2-controller.py backup <name>``: Make a backup copy of inventory database ``<name>``.
+    * ``bw2-controller.py validate <name>``: Validate the data in inventory database ``<name>``.
+    * ``bw2-controller.py versions <name>``: List the versions available of inventory database ``<name>``.
+    * ``bw2-controller.py revert <name> <revision>``: Revert inventory database ``<name>`` to version number ``<revision>``.
+    * ``bw2-controller.py remove <name>``: Deregister inventory database ``<name>``. Does not delete data, only removes it from the Brightway2 register.
+    * ``bw2-controller.py import <path> <name>``: Import a set of inventory data in the Ecospold data format from location ``<path>`` to inventory database ``<name>``.
+    * ``bw2-controller.py export <name> [--include-dependencies]``: Export inventory database ``<name>`` to a bw2package format. If ``--include-dependencies`` is part of the command, the bw2package will include the dependent databases as well.
+    * ``bw2-controller.py setup``: Do the initial setup for when Brightway2 is first installed.
+
+Other online examples
+=====================
+
+<insert link to examples page here>

File docs/usage.rst

-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.
 
 setup(
   name='brightway2',
-  version="0.8.2",
+  version="0.9.0-alpha",
   packages=["brightway2"],
   author="Chris Mutel",
   author_email="cmutel@gmail.com",
   install_requires=packages,
   url="https://bitbucket.org/cmutel/brightway2",
   long_description=open('README').read(),
+  classifiers=[
+    'Development Status :: 4 - Beta',
+    'Intended Audience :: End Users/Desktop',
+    'Intended Audience :: Developers',
+    'Intended Audience :: Science/Research',
+    'License :: OSI Approved :: BSD License',
+    'Operating System :: MacOS :: MacOS X',
+    'Operating System :: Microsoft :: Windows',
+    'Operating System :: POSIX',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 2.7',
+    'Programming Language :: Python :: 2 :: Only',
+    'Topic :: Scientific/Engineering :: Information Analysis',
+    'Topic :: Scientific/Engineering :: Mathematics',
+    'Topic :: Scientific/Engineering :: Visualization',
+    ],
 )