[pitivi] docs: Update hacking formatting and content

[Alexandru Băluț <alexbalut src gnome org>]

commit 0a5af4256ab86c4095782e85653455b7997cda68
Author: Alexandru Băluț <alexandru balut gmail com>
Date:   Wed Jun 1 22:54:29 2016 +0200

    docs: Update hacking formatting and content
    
    Differential Revision: https://phabricator.freedesktop.org/D1051

 docs/HACKING.md |  170 +++++++++++++++++++++++++++---------------------------
 1 files changed, 85 insertions(+), 85 deletions(-)
---
diff --git a/docs/HACKING.md b/docs/HACKING.md
index 266bd38..6f8bf6e 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -1,54 +1,66 @@
 # Hacking on Pitivi
 
-## The pitivi development environment
+## The Pitivi development environment
 
-### Setup pitivi
+### Setup Pitivi
 
 The official way of getting your environment up and running is by using
-[flatpak](http://flatpak.org/)
+[flatpak](http://flatpak.org/).
 
 You first need to [get flatpak](http://flatpak.org/getting.html)
 making sure you also install flatpak-builder, which might be provided by an
 additional package on some distributions (please tell us if it is the case
 for yours so we can make a list here).
 
-Then, create a development environment folder and get the [https://git.gnome.org/browse/pitivi/tree/ Pitivi 
source code] into it:
-
+Create a development environment folder and get the [Pitivi source 
code](https://git.gnome.org/browse/pitivi/tree/) into it:
+```
 $ mkdir pitivi-dev && cd pitivi-dev
 $ git clone https://git.gnome.org/browse/pitivi
 $ cd pitivi/
+```
 
-Finally you just need to run:
-
+Finally to enter the dev env you just need to run:
+```
 $ source bin/pitivi-env
+```
 
 Run `pitivi` while inside the environment to launch Pitivi. Next you should run the unittests.
-After you edit the source code simply run `pitivi` to see how your changes work.
+```
+(ptv-flatpak) $ pitivi
+(ptv-flatpak) $ nosetests tests/test_*.py
+```
 
-### Update the environment
+After you hack the source code simply run `pitivi` again to see how your changes work.
 
-In the `pitivi-env` you can simply run:
+### Update the environment
 
+To update the dependencies installed in the dev env run:
 ```
-ptvenv --update
+(ptv-flatpak) $ ptvenv --update
 ```
 
 That will actually clean the prefix, update all dependencies from their
-git repos and tarballs as defined in the flatpak manifest (located
-in build/flatpak/pitivi.template.json)
+git repos and tarballs as defined in the [flatpak 
manifest](https://git.gnome.org/browse/pitivi/tree/build/flatpak/pitivi.template.json) (located
+at build/flatpak/pitivi.template.json)
 
-### Work on some pitivi dependencies in the development environment
+### Work on some Pitivi dependencies in the development environment
 
-If you have to work on say, [GStreamer Editing 
Service](https://gstreamer.freedesktop.org/modules/gst-editing-services.html)
-you can clone it into you `pitivi-dev`:
+If you have to work on say, [GStreamer Editing 
Services](https://gstreamer.freedesktop.org/modules/gst-editing-services.html)
+you can clone it into your `pitivi-dev` folder:
+```
+(ptv-flatpak) $ git clone git://anongit.freedesktop.org/gstreamer/gst-editing-services
+```
 
+Install it in the sandbox by running in the dev env:
 ```
-    git clone git://anongit.freedesktop.org/gstreamer/gst-editing-services
+(ptv-flatpak) $ autogen
+(ptv-flatpak) $ make install
 ```
 
-Then you can just hack on it, run `autogen` to run `./autogen.sh` with the right arguments for the flatpak 
sandbox,
-and run `make install` to install your changes inside the sandbox (your changes won’t be taken into accout
-without installing).
+`autogen` is an alias which runs `./autogen.sh` with the right arguments
+for the flatpak sandbox.
+`make` is also an alias which runs the real `make` inside the sandbox,
+thus `make install` will install your changes in the sandbox.
 
 NOTE: When updating the environment, it will use your
 local dependencies repositories instead of remote
@@ -56,55 +68,72 @@ repositories, which means you have to update them yourself.
 Also beware that it will not take into account not committed
 changes.
 
-# Coding Style Guide
+## Coding Style Guide
 
-- We rely on the Python Style Guide PEP-8
-       (http://www.python.org/doc/peps/pep-0008/)
+We rely on the [Python Style Guide PEP-8](https://www.python.org/dev/peps/pep-0008/)
 
-  The only exception to it is regarding the "80 columns" rule.
-  Since Python is a very concise/compact language, we can afford to be
-  a little bit more flexible on the line length than languages such as C.
+The only exception to it is regarding the "80 columns" rule.
+Since Python is a very concise/compact language, we can afford to be
+a little bit more flexible on the line length than languages such as C.
 
-  When deciding whether or not you should split your line when it exceeds
-  79 characters, ask yourself: "does it truly improve legibility?"
+When deciding whether or not you should split your line when it exceeds
+79 characters, ask yourself: "Does it truly improve legibility?"
 
-  What this translates to is:
-    - Try to respect the "80 columns/chars" rule of PEP8 when reasonable,
-      that is when the line is really too long.
+What this translates to is:
 
-    - When the contents can fit within the 80 chars,
-      or when it only "slightly" exceeds that limit, keep it on one line.
-      Otherwise, it just hurts legibility and gives a weird "shape" to the code.
+- Avoid having very long lines.
 
-      As you can see, it depends on the context
-      and what you think makes the most easily readable code.
+- When the contents only slightly exceeds the 80 chars limit,
+consider keeping it on one line. Otherwise it just hurts legibility and
+gives a weird "shape" to the code.
 
+### Names
+The function names, method names and other class attributes should be
+small_caps_with_underscore. For example:
+``` lang=python
+def some_function():
+    return ""
 
-  For translatable multiline strings, use Python's implicit line continuation
-  instead of manually concatenating with the plus (+) sign. For example, this
-  is incorrect, gettext will consider it as two separate strings:
-        _("<b>First line</b>\n" +
-          "Some second line that is too long to fit on the first line anyway"
+class MyClass:
 
-  Instead, this is the translator-friendly version:
-        _("<b>First line</b>\n"
-          "Some second line that is too long to fit on the first line anyway"
+    def a_really_important_method(self):
+        self.do_something()
 
-- for method names we use the small_caps_with_underscore style
-  Ex :
+    @property
+    def water_level(self):
+        """The level of the water in meters."""
+        return self.__water_level
+```
 
+To illustrate how private a method or other class field is, prepend
+one or two underscores:
 ``` lang=python
   class MyClass:
 
-     def a_really_important_method(self):
-         self.do_something()
+     def public_method(self):
+         ...
+
+     def _protected_method(self):
+         ...
+
+     def __private_method(self):
+         ...
 ```
 
-- for callbacks, the name of the methods used should:
-  - follow same conventions as normal method names
+Unused arguments in methods should be prefixed with `unused_`.
+The most common place where this would happen is in callbacks from
+gobject signals. For example, below we don't use the second argument,
+but we do use `pad`.
+
+``` lang=python
+     def __pad_added_cb(self, unused_element, pad):
+        self.do_something_with(pad)
+```
+
+The name of a callback method should:
+
   - be prepended with two underscores since it's private
-  - be appended with Cb
-  Ex :
+  - be appended with `cb`
 
 ``` lang=python
   class MyClass:
@@ -116,36 +145,7 @@ changes.
          print "our callback was called"
 ```
 
-- for function names, we use the small_caps_with_underscore style.
-  This enables clear separation between functions and methods.
-
-- for other class attributes we use the same calling convention as
-  for functions:
-  Ex :
-
-``` lang=python
-    @property
-    def water_level(self):
-        """ The level of the water in meters"""
-        return self.__water_level
-```
-
-- unused arguments in method should be prefixed by 'unused_'.
-  The most common place where this would happen is in callbacks from gobject
-  signals:
-  Ex : (we don't use the second argument, but we do use pad)
-
-``` lang=python
-     def _padAddedCb(self, unused_element, pad):
-        ...
-```
-
-- The following naming should be used for class properties/methods:
-  * public : <name>
-  * protected : _<name>
-  * private : __<name>
-
-- Imported modules should be done in this order:
-  * system modules
-  * top-level pitivi modules (ex : pitivi.project)
-  * modules in the same directory
+### Imports order
+You can guess the order of the imported modules by looking at some py files.
+The pre-commit hook has authority in this case as it will reorder the imports
+if the order is not good.