update INSTALL / DEVGUIDE

2 files changed, 70 insertions, 71 deletions

diff --git a/DEVGUIDE.rst b/DEVGUIDE.rst
index e61d0cf9..06595204 100644
--- a/DEVGUIDE.rst
+++ b/DEVGUIDE.rst
@@ -4,16 +4,22 @@ Setup
 
 If you plan on hacking on psutil this is what you're supposed to do first:
 
-- git clone the repo: ``git clone git@github.com:giampaolo/psutil.git``.
-- take a look at `install instructions <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_
-  and satisfy system dependencies first.
+- clone the GIT repository::
+
+  $ git clone git@github.com:giampaolo/psutil.git
+
+- install system deps (see `install instructions <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__).
+
+- install development deps; these are useful for running tests (e.g. mock,
+  unittest2), building doc (e.g. sphinx), running linters (flake8), etc. ::
+
+  $ make setup-dev-env
+
 - bear in mind that ``make`` (see `Makefile <https://github.com/giampaolo/psutil/blob/master/Makefile>`_)
   is the designated tool to run tests, build etc. and that it is also available
   on Windows (see `make.bat <https://github.com/giampaolo/psutil/blob/master/make.bat>`_).
 - (UNIX only) run ``make install-git-hooks``: this will reject your commit
-  if it's not PEP8 compliant.
-- run ``make setup-dev-env``: this will install test deps (e.g. mock lib)
-  and other useful tools (e.g. ipdb, flake8).
+  if python code is not PEP8 compliant.
 - run ``make test`` to run tests.
 
 ============
@@ -29,13 +35,13 @@ Coding style
 Makefile
 ========
 
-Some useful make commands:
+Some useful make commands::
 
-- ``make install``
-- ``make test``
-- ``make test-memleaks``
-- ``make coverage``
-- ``make flake8``
+  $ make install        # install
+  $ make test           # run all tests
+  $ make test-memleaks  # run memory leak tests
+  $ make coverage       # run test coverage
+  $ make flake8         # run PEP8 linter
 
 ====================
 Adding a new feature
@@ -45,23 +51,27 @@ Usually the files involved when adding a new functionality are:
 
 .. code-block:: plain
 
-    psutil/__init__.py            # main psutil namespace
-    psutil/_ps{platform}.py       # python platform wrapper
-    psutil/_psutil_{platform}.c   # C platform extension
-    psutil/_psutil_{platform}.h   # C header file
-    test/test_process|system.py   # main test suite
-    test/test_{platform}.py       # platform specific test suite
+    psutil/__init__.py                   # main psutil namespace
+    psutil/_ps{platform}.py              # python platform wrapper
+    psutil/_psutil_{platform}.c          # C platform extension
+    psutil/_psutil_{platform}.h          # C header file
+    psutil/tests/test_process|system.py  # main test suite
+    psutil/tests/test_{platform}.py      # platform specific test suite
 
 Typical process occurring when adding a new functionality (API):
 
 - define the new function in ``psutil/__init__.py``.
 - write the platform specific implementation in ``psutil/_ps{platform}.py``
   (e.g. ``psutil/_pslinux.py``).
-- if the change requires C code write the C implementation in
+- if the change requires C, write the C implementation in
   ``psutil/_psutil_{platform}.c`` (e.g. ``psutil/_psutil_linux.c``).
-- write a cross platform test in ``psutil/tests/test_{platform}.py``
-  (e.g. ``test_linux.py``).
-- update doc.
+- write a generic test in ``psutil/tests/test_system.py`` or
+  ``psutil/tests/test_process.py``.
+- if possible, write a cross platform test in
+  ``psutil/tests/test_{platform}.py`` (e.g. ``test_linux.py``).
+- update doc in ``doc/index.py``.
+- update ``HISTORY.rst``.
+- update ``README.rst`` (if necessary).
 - make a pull request.
 
 ======================
@@ -70,8 +80,8 @@ Continuous integration
 
 All of the services listed below are automatically run on ``git push``.
 
-Tests
------
+Unit tests
+----------
 
 Tests are automatically run for every GIT push on **Linux**, **OSX** and
 **Windows** by using:
@@ -84,7 +94,7 @@ Test files controlling these are
 and
 `appveyor.yml <https://github.com/giampaolo/psutil/blob/master/appveyor.yml>`_.
 Both services run psutil test suite against all supported python version
-(2.6 - 3.4).
+(2.6 - 3.5).
 Two icons in the home page (README) always show the build status:
 
 .. image:: https://api.travis-ci.org/giampaolo/psutil.png?branch=master
@@ -100,25 +110,24 @@ OSX, FreeBSD and Solaris are currently tested manually (sigh!).
 Test coverage
 -------------
 
-Test coverage is provided by `coveralls.io <https://coveralls.io/github/giampaolo/psutil>`_
-and it is controlled via `.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_.
+Test coverage is provided by `coveralls.io <https://coveralls.io/github/giampaolo/psutil>`_,
+it is controlled via `.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
+and it is update on every git push.
 An icon in the home page (README) always shows the last coverage percentage:
 
 .. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
     :target: https://coveralls.io/github/giampaolo/psutil?branch=master
     :alt: Test coverage (coverall.io)
 
-
 =============
 Documentation
 =============
 
-- doc source code is in `/docs <https://github.com/giampaolo/psutil/tree/master/docs>`_
-  directory.
+- doc source code is written in a single file: `/docs/index.rst <https://raw.githubusercontent.com/giampaolo/psutil/master/docs/index.rst>`_.
 - it uses `RsT syntax <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
   and it's built with `sphinx <http://sphinx-doc.org/>`_.
 - doc can be built with ``make setup-dev-env; cd docs; make html``.
-- public doc is hosted on http://pythonhosted.org/psutil/.
+- public is hosted on http://pythonhosted.org/psutil/.
 - it is uploaded on every new release with ``make upload-doc``.
 
 =======================
diff --git a/INSTALL.rst b/INSTALL.rst
index 49414a2e..d2cb022d 100644
--- a/INSTALL.rst
+++ b/INSTALL.rst
@@ -1,22 +1,20 @@
-.. note::
-    pip is the easiest way to install psutil.
-    It is shipped by default with Python 2.7.9+ and 3.4+. If you're using
-    an older Python version
-    `install pip <https://pip.pypa.io/en/latest/installing/>`__ first.
+*Note: pip is the easiest way to install psutil.
+It is shipped by default with Python 2.7.9+ and 3.4+. If you're using an
+older Python version* `install pip <https://pip.pypa.io/en/latest/installing/>`__
+*first.*
 
-=====
 Linux
 =====
 
-Ubuntu::
+Ubuntu / Debian::
 
-    sudo apt-get install gcc python-dev
-    pip install psutil
+    $ sudo apt-get install gcc python-dev
+    $ pip install psutil
 
 RedHat::
 
-    sudo yum install gcc python-devel
-    pip install psutil
+    $ sudo yum install gcc python-devel
+    $ pip install psutil
 
 OSX
 ===
@@ -26,7 +24,7 @@ first, then:
 
 ::
 
-    pip install psutil
+    $ pip install psutil
 
 Windows
 =======
@@ -35,7 +33,7 @@ The easiest way to install psutil on Windows is to just use the pre-compiled
 exe/wheel installers on
 `PYPI <https://pypi.python.org/pypi/psutil/#downloads>`__ via pip::
 
-    C:\Python27\python.exe -m pip install psutil
+    $ C:\Python27\python.exe -m pip install psutil
 
 If you want to compile psutil from sources you'll need **Visual Studio**
 (Mingw32 is no longer supported):
@@ -50,51 +48,43 @@ Once installed run vcvars64.bat, then you can finally compile (see
 `here <http://stackoverflow.com/questions/11072521/>`__).
 To compile / install psutil from sources on Windows run::
 
-    make.bat build
-    make.bat install
+    $ make.bat build
+    $ make.bat install
 
 FreeBSD
 =======
 
-XXX
+::
+
+    $ pkg install python gcc
+    $ python -m pip install psutil
 
 OpenBSD
 =======
 
-Note - tested on OpenBSD 5.8::
+::
 
-    PKG_PATH=http://mirrors.nycbug.org/pub/OpenBSD/5.8/packages/i386/
-    export PKG_PATH
-    pkg_add -v python
-    python -m pip install psutil
+    $ export PKG_PATH=http://ftp.usa.openbsd.org/pub/OpenBSD/`uname -r`/packages/`arch -s`
+    $ pkg_add -v python gcc
+    $ python -m pip install psutil
 
 NetBSD
 ======
 
-Note - tested on NetBSD 7.0::
+::
 
-    PKG_PATH="http://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/7.0/All"
-    export PKG_PATH
-    pkg_add -v pkgin
-    pkgin install python
-    python -m pip install psutil
+    $ export PKG_PATH="ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/`uname -m`/`uname -r`/All"
+    $ pkg_add -v pkgin
+    $ pkgin install python gcc
+    $ python -m pip install psutil
 
 Solaris
 =======
 
 XXX
 
-========
-Makefile
-========
-
-A makefile is available for both UNIX and Windows (make.bat).  It provides
-some automations for the tasks described above and might be preferred over
-using setup.py. It is useful only if you want to develop for psutil.
-Some useful commands::
+Dev Guide
+=========
 
-    $ make install       # just install (in --user mode)
-    $ make uninstall     # uninstall (needs pip)
-    $ make setup-dev-env # install all dev deps for running tests, building doc, etc
-    $ make test          # run tests
-    $ make clean         # remove installation files
+If you plan on hacking on psutil you may want to take a look at the
+`dev guide <https://github.com/giampaolo/psutil/blob/master/DEVGUIDE.rst>`__.