realpython · kennethreitz · Nov 16, 2012 · Oct 14, 2012 · Oct 14, 2012 · Oct 14, 2012
diff --git a/docs/intro/community.rst b/docs/intro/community.rst
@@ -1,4 +1,4 @@
-.. _the_community:
+.. _the-community:
 
 The Community
 =============

diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
@@ -65,8 +65,8 @@ Python Koans
 
 Python Koans is a port of Edgecase's Ruby Koans.  It uses a test-driven
 approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial
-teaching basic python concepts.  By fixing assertion statements that fail in a
- test script, this provides sequential steps to learning python.
+teaching basic python concepts.  By fixing assertion statements that fail in a 
+test script, this provides sequential steps to learning python.
 
 For those used to languages and figuring out puzzles on their own, this can be
 a fun, attractive option. For those new to python and programming, having an

diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst
@@ -10,8 +10,8 @@ Nearly all Python database modules such as `sqlite3`, `psycopg` and
 `mysql-python` conform to this interface.
 
 Tutorials that explain how to work with modules that conform to this interface can be found
-`here <http://halfcooked.com/presentations/osdc2006/python_databases.html>`_ and
-`here <http://www.amk.ca/python/writing/DB-API.html>`_.
+`here <http://halfcooked.com/presentations/osdc2006/python_databases.html>`__ and
+`here <http://www.amk.ca/python/writing/DB-API.html>`__.
 
 SQLAlchemy
 ----------

diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
@@ -1,6 +1,8 @@
 Picking an Interpreter
 ======================
 
+.. _which-python:
+
 Which Python to use?
 
 

diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
@@ -266,7 +266,7 @@ logic (called pure functions) allow the following benefits:
 - Pure functions are easier to test with unit-tests: There is less
   need for complex context setup and data cleaning afterwards.
 
-- Pure functions are easier to manipulate, decorate_, and pass-around.
+- Pure functions are easier to manipulate, decorate, and pass-around.
 
 In summary, pure functions, without any context or side-effects, are more
 efficient building blocks than classes and objects for some architectures.

diff --git a/docs/writing/style.rst b/docs/writing/style.rst
@@ -114,10 +114,10 @@ Those two possibilities are better avoided without any strong reason to not
 follow the syntax that is the closest to the function definition: ``send('Hello',
 'World', cc='Cthulhu', bcc='God')``.
 
-As a side note, following YAGNI_ principle, it is often harder to remove an
-optional argument (and its logic inside the function) that was added "just in
-case" and is seemingly never used, than to add a new optional argument and its
-logic when needed.
+As a side note, following `YAGNI <http://en.wikipedia.org/wiki/You_ain't_gonna_need_it>`_
+principle, it is often harder to remove an optional argument (and its logic inside the 
+function) that was added "just in case" and is seemingly never used, than to add a 
+new optional argument and its logic when needed.
 
 The **arbitrary argument list** is the third way to pass arguments to a
 function.  If the function intention is better expressed by a signature with an
@@ -416,12 +416,12 @@ Then run it on a file or series of files to get a report of any violations.
     optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
 
 Conventions
-:::::::::::
+----------------
 
 Here are some conventions you should follow to make your code easier to read.
 
 Check if variable equals a constant
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You don't need to explicitly compare a value to True, or None, or 0 - you can
 just add it to the if statement. See `Truth Value Testing
@@ -455,7 +455,7 @@ list of what is considered false.
         print 'attr is None!'
 
 Access a Dictionary Element
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass
 a default argument to ``get``.
@@ -484,7 +484,7 @@ a default argument to ``get``.
         print d['hello']
 
 Short Ways to Manipulate Lists
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `List comprehensions
 <http://docs.python.org/tutorial/datastructures.html#list-comprehensions>`_
@@ -548,7 +548,7 @@ manually. Moreover,
 it is better optimized for iterators.
 
 Read From a File
-----------------
+~~~~~~~~~~~~~~~~
 
 Use the ``with open`` syntax to read from files. This will automatically close
 files for you.
@@ -574,7 +574,7 @@ The ``with`` statement is better because it will ensure you always close the
 file, even if an exception is raised.
 
 Returning Multiple Values from a Function
------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Python supports returning multiple values from a function as a comma-separated
 list, so you don't have to create an object or dictionary and pack multiple