#14141: Use :doc: crossref Sphinx role for inter document links
---------------------------+------------------------------------------------
Reporter: ramiro | Owner: nobody
Status: new | Milestone:
Component: Documentation | Version: SVN
Keywords: | Stage: Unreviewed
Has_patch: 1 |
---------------------------+------------------------------------------------
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).
--
Ticket URL: <http://code.djangoproject.com/ticket/14141>
Django <http://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
