README: Further tweaks

- Use more standard header characters
- Move Python invocation to a separate section
- Correct capitalization of doc8

Change-Id: I9ddddf216886ca91d5c1c381474bd008ce151f57
Signed-off-by: Stephen Finucane <stephen@that.guru>

Author: stephenfin

README.rst

@@ -13,28 +13,27 @@
    :alt: GitHub last commit
 
 ====
-Doc8
+doc8
 ====
 
-Doc8 is an *opinionated* style checker for `rst`_ (with basic support for
+*doc8* is an *opinionated* style checker for rst__ (with basic support for
 plain text) styles of documentation.
 
-QuickStart
-==========
+__ http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+
+Quick start
+-----------
 
 ::
 
     pip install doc8
 
-To run doc8 just invoke it against any doc directory::
+To run *doc8*, just invoke it against any documentation directory::
 
     $ doc8 cool-project/docs
 
 Usage
-=====
-
-Command line usage
-******************
+-----
 
 ::
 
@@ -91,8 +90,8 @@ Command line usage
       -v, --verbose         run in verbose mode.
       --version             show the version and exit.
 
-Ini file usage
-**************
+INI file usage
+~~~~~~~~~~~~~~
 
 Instead of using the CLI for options the following files will also be examined
 for ``[doc8]`` sections that can also provide the same set of options. If
@@ -118,35 +117,11 @@ An example section that can be placed into one of these files::
 only variation of this being the ``no-sphinx`` option which from the
 configuration file will be ``sphinx`` instead).
 
-Python Usage
-************
-
-To call doc8 from a Python project do::
-
-    from doc8 import doc8
-
-    result = doc8(allow_long_titles=True, max_line_length=99)
-
-The returned ``result`` will have the following attributes and methods:
-
-* ``result.files_selected`` - number of files selected
-* ``result.files_ignored`` - number of files ignored
-* ``result.error_counts`` - ``dict`` of ``{check_name: error_count}``
-* ``result.total_errors`` - total number of errors found
-* ``result.errors`` - list of
-  ``(check_name, filename, line_num, code, message)`` tuples
-* ``result.report()`` - returns a human-readable report as a string
-
-Note that calling ``doc8`` in this way will not write to stdout, so the
-``quiet`` and ``verbose`` options are ignored.
-
-
 Option conflict resolution
-**************************
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When the same option is passed on the command line and also via configuration
-files the following strategies are applied to resolve these types
-of conflicts.
+files the following strategies are applied to resolve these types of conflicts.
 
 ======================   ===========  ========
 Option                   Overrides    Merges
@@ -169,4 +144,29 @@ option (for example by becoming a larger list or set of values that contains
 the values passed on the command line *and* the values passed via
 configuration).
 
-.. _rst: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+
+API
+---
+
+It is also possible to use *doc8* programmatically. To call *doc8* from a
+Python project, use::
+
+    from doc8 import doc8
+
+    result = doc8(allow_long_titles=True, max_line_length=99)
+
+The returned ``result`` will have the following attributes and methods:
+
+* ``result.files_selected`` - number of files selected
+* ``result.files_ignored`` - number of files ignored
+* ``result.error_counts`` - ``dict`` of ``{check_name: error_count}``
+* ``result.total_errors`` - total number of errors found
+* ``result.errors`` - list of
+  ``(check_name, filename, line_num, code, message)`` tuples
+* ``result.report()`` - returns a human-readable report as a string
+
+The ``doc8`` method accepts the same arguments as the executable. Simply
+replace hyphens with underscores.
+
+**Note:** Calling ``doc8`` in this way will not write to stdout, so the
+``quiet`` and ``verbose`` options are ignored.