docs: markup fixes, separate section for api docs, link to demo video, improved phrasing

docs/api.rst

@@ -0,0 +1,8 @@
+=================
+API Documentation
+=================
+
+.. toctree::
+   :glob:
+
+   api/**

docs/index.rst

@@ -8,6 +8,11 @@ Welcome to the Let's Encrypt client documentation!
    using
    project
 
+.. toctree::
+   :maxdepth: 1
+
+   api
+
 
 Indices and tables
 ==================

docs/project.rst

@@ -2,6 +2,8 @@
 The Let's Encrypt Client Project
 ================================
 
+.. _hacking:
+
 Hacking
 =======
 
@@ -12,47 +14,52 @@ environment:
 
     ./venv/bin/python setup.py dev
 
-The code base, including your pull requests, **must have 100% test statement
-coverage and be compliant with the [coding style](#coding-style)**.
+The code base, including your pull requests, **must** have 100% test statement
+coverage **and** be compliant with the :ref:`coding-style`.
 
 The following tools are there to help you:
 
-- `./venv/bin/tox` starts a full set of tests. Please make sure you
+- ``./venv/bin/tox`` starts a full set of tests. Please make sure you
   run it before submitting a new pull request.
 
-- `./venv/bin/tox -e cover` checks the test coverage only.
+- ``./venv/bin/tox -e cover`` checks the test coverage only.
 
-- `./venv/bin/tox -e lint` checks the style of the whole project,
-  while `./venv/bin/pylint --rcfile=.pylintrc file` will check a single `file` only.
+- ``./venv/bin/tox -e lint`` checks the style of the whole project,
+  while ``./venv/bin/pylint --rcfile=.pylintrc file`` will check a single `file` only.
 
 
+.. _coding-style:
+
 Coding style
 ============
 
-Most importantly, **be consistent with the rest of the code**, please.
+Please:
 
-1. Read [PEP 8 - Style Guide for Python Code]
-(https://www.python.org/dev/peps/pep-0008).
+1. **Be consistent with the rest of the code**.
 
-2. Follow [Google Python Style Guide]
-(https://google-styleguide.googlecode.com/svn/trunk/pyguide.html),
-with the exception that we use [Sphinx](http://sphinx-doc.org/)-style
-documentation:
+2. Read `PEP 8 - Style Guide for Python Code`_.
 
-::
+3. Follow the `Google Python Style Guide`_, with the exception that we
+   use `Sphinx-style`_ documentation:
 
-    def foo(arg):
-        """Short description.
+    ::
 
-        :param int arg: Some number.
+        def foo(arg):
+            """Short description.
 
-        :returns: Argument
-        :rtype: int
+            :param int arg: Some number.
 
-        """
-        return arg
+            :returns: Argument
+            :rtype: int
 
-3. Remember to use `./venv/bin/pylint`.
+            """
+            return arg
+
+4. Remember to use ``./venv/bin/pylint``.
+
+.. _Google Python Style Guide: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+.. _Sphinx-style: http://sphinx-doc.org/
+.. _PEP 8 - Style Guide for Python Code: https://www.python.org/dev/peps/pep-0008
 
 
 Updating the Documentation
@@ -67,12 +74,4 @@ In order to generate the Sphinx documentation, run the following commands.
     make clean html SPHINXBUILD=../venv/bin/sphinx-build
 
 
-This should generate documentation in the `docs/_build/html` directory.
-
-API documentation
-=================
-
-.. toctree::
-   :glob:
-
-   api/**
+This should generate documentation in the ``docs/_build/html`` directory.

docs/using.rst

@@ -6,16 +6,17 @@ Prerequisites
 =============
 
 The demo code is supported and known to work on **Ubuntu only** (even
-closely related [Debian is known to fail]
-(https://github.com/letsencrypt/lets-encrypt-preview/issues/68)).
+closely related `Debian is known to fail`_).
 
 Therefore, prerequisites for other platforms listed below are provided
-mainly for the [developers](#hacking) reference.
+mainly for the :ref:`developers <hacking>` reference.
 
 In general:
 
 * `swig`_ is required for compiling `m2crypto`_
-* `augeas`_ is required for the `python-augeas` bindings
+* `augeas`_ is required for the ``python-augeas`` bindings
+
+.. _Debian is known to fail: https://github.com/letsencrypt/lets-encrypt-preview/issues/68
 
 Ubuntu
 ------
@@ -30,6 +31,7 @@ Mac OSX
 -------
 
 ::
+
     sudo brew install augeas swig