Use :doc: crossref Sphinx role for inter document links

[Ramiro Morales]

This new role ​available since Sphinx 0.6 allows to link to other documents by using :doc:`/foo/bar` or :doc:`Foo Bar</foo/bar>` insted of their :ref:.. counterparts without the need to add an explicit reST label at the top of the target document.

This has the following advantages:

• No need to add explicit destination labels at the top of every document anymore.
• The links are more accurate (e.g. in the HTML version of the docs, once clicked the entire document is shown and the browser doesn't scroll to the location of the target anchor)
• Gives readers of the .txt version better hints about the real location of the linked document.

disadvantages:

• Slightly more verbose (:ref:`foo-bar` v. :doc:`/foo/bar` or even :doc:`/foo/bar/index` in some cases)
• Makes document links more dependent of the file system layout, could result link breakage when big refactoring is applied to content.

The attached patch changes this all over our docs fixing a few reST typos in the process. The doc labels and links between docs under ref/contrib/gis are left untouched because Justin seems to be using them to keep the name of the references short and I don't want to interfere with his work, considering that he maintains the GeoDjango code in another repository.

The patch also applies without conflicts to the 1.2.X branch as of now (r13607).

[Ramiro Morales]

Compressed patch. Trac gives me "500 Internal Server Error (Maximum attachment size: 262144 bytes)"

[Ramiro Morales]

Attached a gzipped version of the patch so Trac is happy. A reviewable copy is available at ​http://paste.pocoo.org/show/252129/

[Jacob]

(In [13608]) Fixed #14141: docs now use the :doc: construct for links between documents.

Thanks, Ramiro Morales.