Add CONTRIBUTING file; include in contribute.rst

GitHub recently added a feature that looks for a CONTRIBUTING file in
repo root and displays it whenever a user creates an issue or submits a
pull request. I took this opportunity to put some contribution
submission guidelines into that file, including it dynamically inside
our existing docs/contribute.rst file to eliminate unnecessary
redundancy.

docs/contribute.rst

@@ -1,29 +1,34 @@
-How to contribute?
-###################
-There are many ways to contribute to Pelican. You can enhance the
-documentation, add missing features, and fix bugs (or just report them).
+How to contribute
+#################
 
-Don't hesitate to fork and make a pull request on GitHub. When doing so, please
-create a new feature branch as opposed to making your commits in the master
-branch.
+There are many ways to contribute to Pelican. You can improve the
+documentation, add missing features, and fix bugs (or just report them). You
+can also help out by reviewing and commenting on
+`existing issues <https://github.com/getpelican/pelican/issues>`_.
+
+Don't hesitate to fork Pelican and submit a pull request on GitHub. When doing
+so, please adhere to the following guidelines.
+
+.. include:: ../CONTRIBUTING.rst
 
 Setting up the development environment
 ======================================
 
-You're free to set up your development environment any way you like. Here is a
-way using the `virtualenv <http://www.virtualenv.org/>`_ and `virtualenvwrapper
-<http://www.doughellmann.com/projects/virtualenvwrapper/>`_ tools. If you don't
-have them, you can install these both of these packages via::
+While there are many ways to set up one's development environment, following
+is a method that uses `virtualenv <http://www.virtualenv.org/>`_. If you don't
+have ``virtualenv`` installed, you can install it via::
 
-    $ pip install virtualenvwrapper
+    $ pip install virtualenv
 
 Virtual environments allow you to work on Python projects which are isolated
 from one another so you can use different packages (and package versions) with
 different projects.
 
-To create a virtual environment, use the following syntax::
+To create and activate a virtual environment, use the following syntax::
 
-    $ mkvirtualenv pelican
+    $ virtualenv pelican ~/virtualenvs/pelican
+    $ cd ~/virtualenvs/pelican
+    $ . bin/activate
 
 To clone the Pelican source::
 
@@ -38,59 +43,76 @@ To install Pelican and its dependencies::
 
     $ python setup.py develop
 
+Coding standards
+================
+
+Try to respect what is described in the `PEP8 specification
+<http://www.python.org/dev/peps/pep-0008/>`_ when making contributions. This
+can be eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
+<http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
+particular will give you some useful hints about ways in which the
+code/formatting can be improved.
+
+Building the docs
+=================
+
+If you make changes to the documentation, you should preview your changes
+before committing them::
+
+    $ pip install sphinx
+    $ cd src/pelican/docs
+    $ make html
+
+Open ``_build/html/index.html`` in your browser to preview the documentation.
+
 Running the test suite
 ======================
 
 Each time you add a feature, there are two things to do regarding tests:
-checking that the existing tests pass, and adding tests for the new feature
+check that the existing tests pass, and add tests for the new feature
 or bugfix.
 
-The tests live in "pelican/tests" and you can run them using the
-"discover" feature of unittest2::
+The tests live in ``pelican/tests`` and you can run them using the
+"discover" feature of ``unittest``::
 
-    $ unit2 discover
+    $ python -m unittest discover
 
-If you have made changes that affect the output of a Pelican-generated weblog,
-then you should update the output used by functional tests.
-To do so, you can use the following two commands::
+After making your changes and running the tests, you may see a test failure
+mentioning that "some generated files differ from the expected functional tests
+output." If you have made changes that affect the HTML output generated by
+Pelican, and the changes to that output are expected and deemed correct given
+the nature of your changes, then you should update the output used by the
+functional tests. To do so, you can use the following two commands::
 
     $ pelican -o pelican/tests/output/custom/ -s samples/pelican.conf.py \
         samples/content/
     $ pelican -o pelican/tests/output/basic/ samples/content/
 
-testing for python3
--------------------
+Testing on Python 3.x
+---------------------
 
-On Python 3, if you have installed the Py3k compatible versions of the
-plugins manual testing with ``unit2 discover`` is also straightforward.
+Testing on Python 3.x currently requires some extra steps: installing
+Python 3.x-compatible versions of dependent packages and plugins.
 
-However, you must tell tox to use those Py3k libraries. If you forget this,
-tox will pull the regular packages from PyPi and the tests will fail.
+However, you must tell ``tox`` to use those Python 3.x-compatible libraries.
+If you forget this, ``tox`` will pull the regular packages from PyPI, and the
+tests will fail.
 
-Tell tox about the local packages thusly: enter the source directory of
-smartypants and run tox there. Do this again for typogrify and webassets.
-Smartypants and typogrify do not have real tests, and webassets will fail
-noisily, but as a result we get these libraries neatly packaged in tox's
-distshare directory. And this we need to run tox for Pelican.
+Tell ``tox`` about the local packages thusly: enter the source directory of
+smartypants and run ``tox`` there. Do this again for the ``typogrify`` and
+``webassets`` packages. SmartyPants and Typogrify do not have real tests, and
+``webassets`` will fail noisily, but as a result we get these libraries neatly
+packaged in tox's ``distshare`` directory, which we need in order to run
+``tox`` for Pelican.
 
-Coding standards
-================
+Python 3.x development tips
+===========================
 
-Try to respect what is described in the `PEP8 specification
-<http://www.python.org/dev/peps/pep-0008/>`_ when providing patches. This can be
-eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
-<http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
-particular will give you some useful hints about ways in which the
-code/formatting can be improved.
+Here are some tips that may be useful when doing some code for both Python 2.7
+and Python 3.x at the same time:
 
-Python3 support
-===============
+- Assume every string and literal is unicode (import unicode_literals):
 
-Here are some tips that may be useful when doing some code for both python2 and
-python3 at the same time:
-
-- Assume, every string and literal is unicode (import unicode_literals):
- 
   - Do not use prefix ``u'``.
   - Do not encode/decode strings in the middle of sth. Follow the code to the
     source (or target) of a string and encode/decode at the first/last possible