CONTRIBUTING.rst: linkify, improve markup
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 539da50..ff1a619 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,10 +1,21 @@
+Process
+=======
+
This repository has a mandatory code review policy. Contributions
should happen through pull requests. Never commit to ``master``
directly.
-When in doubt, refer to PEP 8 for Python code.
+Code
+====
-Write docstrings like this::
+When in doubt, refer to `PEP 8`_ for Python code.
+
+Docs
+====
+
+Write docstrings like this:
+
+.. code-block:: python
def some_function(some_arg):
"""
@@ -18,4 +29,8 @@
- Always use three double quotes.
- Put the three double quotes on their own line.
- No blank line at the end.
-- Use Sphinx parameter/attribute documentation syntax.
+- Use Sphinx parameter/attribute documentation `syntax`_.
+
+
+.. _`PEP 8`: http://www.peps.io/8/
+.. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists