id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
14141	Use :doc: crossref Sphinx role for inter document links	Ramiro Morales	nobody	"This new role [http://sphinx.pocoo.org/markup/inline.html#role-doc 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)."		closed	Documentation	dev		fixed			Unreviewed	1	0	0	0	0	0