Improve and refactor doc readme

- Fix indentation / code blocks. Tabs to spaces. Refactor sections.
- Improvements for dual reST+markdown compatibility

doc/README.md

@@ -2,47 +2,48 @@ Kivy - Documentation
 ====================
 
 You can access the latest documentation on the web:
-  * http://kivy.org/docs
 
+* http://kivy.org/docs
 
-How to build the documentation
+Contributing
-------------------------------
+------------
 
-You need to install:
+If you intend on editing and contributing documentation, assure the kivy source
+code is up to date before proceeding. If your documentation is outdated, it
+could result in merge conflicts.
 
-  * Python Sphinx
+Install Sphinx
-    - With pip:
+--------------
-    ```
-	pip install sphinx
-	```
 
-    - With apt-get:
+- With pip:
-    ```
+  
-    apt-get install python-sphinx
+  ``pip install sphinx``
-    ```
 
-    - With MacPorts:
+- With apt-get:
-    ```
+    
-	port install py34-sphinx
+  ``apt-get install python-sphinx``
-	```
 
-    - On Windows (or from inside your virtualenv):
+- With MacPorts:
+  
+  ``port install py34-sphinx``
 
-          Get pip (https://pypi.python.org/pypi/pip). You'll use it to install the dependencies.
+- On Windows (or from inside your virtualenv):
 
-          To install pip, run python setup.py install in the pip directory. Now run:
+  Get pip (https://pypi.python.org/pypi/pip). You'll use it to install the dependencies.
-          ```
-          pip install sphinxcontrib-blockdiag sphinxcontrib-seqdiag
-          pip install sphinxcontrib-actdiag sphinxcontrib-nwdiag
-          ```
-          Or just use the provided `doc-requirements.txt`:
-          ```
-          pip install -r doc-requirements.txt
-          ```
 
-  * Latest kivy
+  To install pip, run ``python setup.py install`` in the pip directory. Now run:
+    
+  ``pip install sphinxcontrib-blockdiag sphinxcontrib-seqdiag``
+  
+  ``pip install sphinxcontrib-actdiag sphinxcontrib-nwdiag``
+    
+  Or just use the provided *doc-requirements.txt*:
+    
+  ``pip install -r doc-requirements.txt``
+  
+Building the documentation
+--------------------------
 
-Generate documentation using make: `make html`.
+Generate documentation using make: ``make html``.
-
-Documentation will be accessible in `build/html/`.
 
+Documentation will be accessible in ``build/html/``.