Opened 8 years ago

Closed 8 years ago

#14141 closed (fixed)

Use :doc: crossref Sphinx role for inter document links

Reported by: Ramiro Morales Owned by: nobody
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


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.


  • 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).

Attachments (1)

doclinks.diff.gz (91.1 KB) - added by Ramiro Morales 8 years ago.
Compressed patch. Trac gives me "500 Internal Server Error (Maximum attachment size: 262144 bytes)"

Download all attachments as: .zip

Change History (3)

Changed 8 years ago by Ramiro Morales

Attachment: doclinks.diff.gz added

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

comment:1 Changed 8 years ago by Ramiro Morales

Attached a gzipped version of the patch so Trac is happy. A reviewable copy is available at

comment:2 Changed 8 years ago by Jacob

Resolution: fixed
Status: newclosed

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

Thanks, Ramiro Morales.

Note: See TracTickets for help on using tickets.
Back to Top