A few documentation improvements.

docs/docs/installation.rst

@@ -3,8 +3,8 @@
 Installation and Configuration
 ==============================
 
-The preferred way
------------------
+The preferred way (pip)
+-----------------------
 
 On any system you can install |parso| directly from the Python package index
 using pip::

docs/docs/usage.rst

@@ -9,7 +9,8 @@ can also be created by directly instantiating ``Grammar``. More information
 about the resulting objects can be found in the :ref:`parser tree documentation
 <parser-tree>`.
 
-The simplest way of using parso is without even loading a grammar:
+The simplest way of using parso is without even loading a grammar
+(:py:func:`parso.parse`):
 
 .. sourcecode:: python
 
@@ -17,7 +18,14 @@ The simplest way of using parso is without even loading a grammar:
    >>> parso.parse('foo + bar')
    <Module: @1-1>
 
-.. automodule:: parso.grammar
+Typically if you want to work with one specific Python version, use:
+
+.. autofunction:: parso.load_grammar
+
+You will get back a grammar object that you can use to parse code and find
+issues in it:
+
+.. autoclass:: parso.grammar.Grammar
     :members:
     :undoc-members:
 
@@ -25,17 +33,18 @@ The simplest way of using parso is without even loading a grammar:
 Utility
 -------
 
+There are some utility functions that 
+
 .. autofunction:: parso.parse
 
-.. automodule:: parso.utils
-    :members:
-    :undoc-members:
+.. autofunction:: parso.split_lines
+.. autofunction:: parso.python_bytes_to_unicode
 
 
 Used By
 -------
 
-- jedi_ (which is used by IPython and a lot of plugins).
+- jedi_ (which is used by IPython and a lot of editor plugins).
 
 
 .. _jedi: https://github.com/davidhalter/jedi

parso/__init__.py

@@ -21,6 +21,7 @@ hello + 1
 
 from parso.parser import ParserSyntaxError
 from parso.grammar import Grammar, load_grammar
+from parso.utils import split_lines, python_bytes_to_unicode
 
 
 __version__ = '0.0.5'

parso/grammar.py

@@ -19,10 +19,11 @@ _loaded_grammars = {}
 
 class Grammar(object):
     """
-    Create custom grammars by calling this. It's not really supported, yet.
+    :py:func:`parso.load_grammar` returns instances of this class.
 
-    :param text: A BNF representation of your grammar.
+    Creating custom grammars by calling this is not supported, yet.
     """
+    #:param text: A BNF representation of your grammar.
     _error_normalizer_config = None
     _token_namespace = None
     _default_normalizer_config = pep8.PEP8NormalizerConfig()
@@ -237,10 +238,10 @@ class PythonFStringGrammar(Grammar):
 
 def load_grammar(**kwargs):
     """
-    Loads a Python grammar. The default version is the current Python version.
+    Loads a :py:class:`parso.Grammar`. The default version is the current Python
+    version.
 
-    If you need support for a specific version, please use e.g.
-    `version='3.3'`.
+    :param str version: A python version string, e.g. ``version='3.3'``.
     """
     def load_grammar(language='python', version=None):
         if language == 'python':