[gnome-music/wip/mschraal/readme: 2/2] README: Rename with markdown extension

[Marinus Schraal <mschraal src gnome org>]

commit ee096321397edcc78801c0e700d8a5cb74337254
Author: Marinus Schraal <mschraal gnome org>
Date:   Tue Dec 19 09:24:52 2017 +0100

    README: Rename with markdown extension
    
    Cleanup & markdown the contents of the readme. Extend the code style
    section.
    
    Leave README as a shim while still using autotools.

 README    | 52 +----------------------------------------
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 51 deletions(-)
---
diff --git a/README b/README
index a87c632..96dc92f 100644
--- a/README
+++ b/README
@@ -1,51 +1 @@
-GNOME Music
-===========
-
-Music is the new GNOME music playing application.
-
-
-=== Where can I find more? ===
-
-We have a wiki page at
-https://wiki.gnome.org/Apps/Music
-
-You can join us on the IRC:
-#gnome-music on GIMPNet
-
-
-=== Building from jhbuild ===
-
-Follow the BuildGnome tutorial for newcomers at https://wiki.gnome.org/Newcomers/BuildGnome
-
-After installing jhbuild, you have to build gnome-music and all its dependencies. The task can be done by 
simply running:
-$ jhbuild sysdeps --install gnome-music
-$ jhbuild build gnome-music
-
-Finally, start gnome music with:
-$ jhbuild run gnome-music
-
-
-=== Troubleshooting ===
-
-Jhbuild fires import errors for python packages like:
-"ImportError: /opt/gnome/lib64/python2.7/site-packages/"
-Do:
- $ jhbuild shell
- $ export PYTHONPATH=/opt/gnome/lib/python3.3/site-packages:/opt/gnome/lib64/python3.3/site-packages
- $ gnome-music
-
-
-=== Coding style ===
-
-GNOME Music is written in Python and aspires to adhere to the coding style described in PEP-8:
-https://www.python.org/dev/peps/pep-0008/
-
-Use of docstrings is recommended following PEP-257:
-https://www.python.org/dev/peps/pep-0257/
-
-The content of docstrings uses the Sphinx markup style:
-http://www.sphinx-doc.org/
-
-Use PyGI shorthands for manipulating GtkTreeModel:
- model[iter][0] = "artist"
- artist, title = model[iter][1, 4]
+See README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5fea6d2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+Music is the new GNOME music playing application.
+
+# Where can I find more?
+
+Music has a wiki page at
+https://wiki.gnome.org/Apps/Music (outdated).
+
+You can join the developers on IRC: [#gnome-music](irc://irc.gnome.org/gnome-music) on 
[GIMPNet](https://wiki.gnome.org/Community/GettingInTouch/IRC).
+
+# Join the development
+
+Follow the guide at https://wiki.gnome.org/Newcomers/ and choose Music as your project. There are bugs 
labeled for newcomers, which should provide an easy entry point. Of course, feel free to pick something more 
challenging. Pick bugs if you can, the goal is to make the current Music experience sound & stable and only 
then extend it's functionality.
+
+# Coding style
+
+GNOME Music is written in Python and aspires to adhere to the coding style described in the python style 
guide [PEP-8](https://www.python.org/dev/peps/pep-0008/).
+
+Since Music was written over many years and by many different contributors without a single style being 
enforced, it currently is in a mixed style state. The goal is to eventually consistently follow  
[PEP-8](https://www.python.org/dev/peps/pep-0008/) for style and 
[PEP-257](https://www.python.org/dev/peps/pep-0257/) for docstrings. The content of docstrings uses the 
[Sphinx markup style](http://www.sphinx-doc.org/).
+
+Docstrings should be added to all (new) public functions.
+
+Since looking at the surrounding code might give mixed results, take note of the following rules as a basic 
style guide.
+
+### Line length
+>>>
+Limit all lines to a maximum of 79 characters.
+
+For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length 
should be limited to 72 characters.
+>>>
+
+### Indentation
+
+Music uses hanging indents when the lines get too long.
+>>>
+When using a hanging indent the following should be considered; there should be no arguments on the first 
line and further indentation should be used to clearly distinguish itself as a continuation line.
+>>>
+
+```python
+# More indentation included to distinguish this from the rest.
+def long_function_name(
+        var_one, var_two, var_three,
+        var_four):
+    print(var_one)
+
+# Hanging indents should add a level.
+foo = long_function_name(
+    var_one, var_two,
+    var_three, var_four)
+```
+
+### Line break before a binary operator
+
+```python
+# Yes: easy to match operators with operands
+income = (gross_wages
+          + taxable_interest
+          + (dividends - qualified_dividends)
+          - ira_deduction
+          - student_loan_interest)
+
+# Add some extra indentation on the conditional continuation line.
+if (this_is_one_thing
+        and that_is_another_thing):
+    do_something()
+```
+
+### Class internals
+
+All non-public classwide variables or methods should be prepended with an underscore.
+>>>
+_single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects 
whose name starts with an underscore.
+>>>
+
+### PyGI specific
+
+Use PyGI shorthands for manipulating `GtkTreeModel` & `GtkListStore`:
+```python
+model[iter][0] = "artist"
+artist, title = model[iter][1, 4]
+```