Merge branch 'update-contrib-docs'

sebastinas · sebastinas · commit 8ad41e8faeed · 2015-01-12T23:35:57.000+01:00
diff --git a/doc/sphinx/source/contributing.rst b/doc/sphinx/source/contributing.rst
@@ -18,20 +18,21 @@ Getting your development environment set up
 
 bpython supports Python 2.6, 2.7, 3.3 and 3.4. The code is written in Python
 2 and transformed for Python 3 with 2to3. This means that it's easier
-to work on bpython with Python 2 because it's you can use `python setup.py develop`
+to work on bpython with Python 2 because you can use ``python setup.py develop``
+or ``pip install -e .``
 (`development mode
 <https://pythonhosted.org/setuptools/setuptools.html#development-mode>`_ installs
 by linking to the bpython source instead of copying it over)
 in a more straightforward way to have your changes immediately reflected by
-your bpython installation and the `bpython`, `bpython-curtsies`, and `bpython-urwid`
+your bpython installation and the `bpython`, `bpython-curses`, and `bpython-urwid`
 commands.
 
 Using a virtual environment is probably a good idea. Create a virtual environment with
 
 .. code-block:: bash
 
     $ virtualenv bpython-dev            # determines Python version used
-    $ source bpython-dev/bin/activate   # necssary every time you work on bpython
+    $ source bpython-dev/bin/activate   # necessary every time you work on bpython
 
 Fork bpython in the GitHub web interface, then clone the repo:
 
@@ -40,28 +41,53 @@ Fork bpython in the GitHub web interface, then clone the repo:
     $ git clone git@github.com:YOUR_GITHUB_USERNAME/bpython.git
     $ # or "git clone https://github.com/YOUR_GITHUB_USERNAME/bpython.git"
 
-Next install the dependencies and install your development copy of bpython:
+Next install the install your development copy of bpython and its dependencies:
 
 .. code-block:: bash
 
-    $ pip install pygments requests                  # install required dependencies
-    $ pip install curtsies greenlet watchdog urwid   # install optional dependencies
-    $ pip install sphinx mock nosetests              # development dependencies
     $ cd bpython
-    $ python setup.py develop
+    $ pip install -e .                       # install bpython and required dependencies
+    $ pip install watchdog urwid             # install optional dependencies
+    $ pip install sphinx mock nose           # development dependencies
     <modify a file in some way>
-    $ bpython-curtsies      # this runs your modified copy of bpython!
+    $ bpython                                # this runs your modified copy of bpython!
 
-As a first dev task, I recommend getting `bpython` to print your name every time you hit a specific key.
+.. note::
+
+    Many requirements are also available from your distribution's package
+    manager. On Debian/Ubuntu based systems, the following packages can be used:
+
+    .. code-block:: bash
+
+        $ sudp apt-get install python-greenlet python-pygments python-requests
+        $ sudo apt-get install python-watchdog python-urwid
+        $ sudo apt-get install python-sphinx python-mock python-nose
+
+    Rememeber to replace ``python`` with ``python3`` in every package name if
+    you intend to develop with Python 3. You also need to run `virtualenv` with
+    `--system-site-packages` packages, if you want to use the packages provided
+    by your distribution.
+
+.. note::
+
+    Installation of some dependencies with ``pip`` requires Python headers and a
+    C compiler. These are also available from your package manager.
+
+    .. code-block:: bash
+
+        $ sudo apt-get install gcc python-dev
+
+As a first dev task, I recommend getting `bpython` to print your name every
+time you hit a specific key.
 
 To run tests from the bpython directory:
 
 .. code-block:: bash
 
     $ nosetests
 
-To build the docs:
-------------------
+Building the documentation
+--------------------------
 
 The documentation is included in the bpython repository. After
 checking out the bpython repository and installing `sphinx` as described in
@@ -75,7 +101,7 @@ repository to build the documentation:
 Afterwards you can point your browser to `doc/sphinx/build/html/index.html`.
 Don't forget to recreate the HTML after you make changes.
 
-To hack on the site or theme
+Hacking on the site or theme
 ----------------------------
 
 The site (and its theme as well) is stored in a separate repository and built using
