From 9dcb2cf4e639650ae430aa3cac7797c131559294 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Tue, 19 Aug 2014 10:22:51 -0400
Subject: [PATCH] [1.7.x] Added sphinx extension to ease generation of ticket
 links.

Backport of fca677fa43 from master
---
 docs/_ext/ticket_role.py                      | 38 +++++++++++++++++++
 docs/conf.py                                  | 10 ++++-
 .../contributing/writing-documentation.txt    |  4 ++
 docs/releases/1.6.6.txt                       | 25 +++++-------
 4 files changed, 61 insertions(+), 16 deletions(-)
 create mode 100644 docs/_ext/ticket_role.py

diff --git a/docs/_ext/ticket_role.py b/docs/_ext/ticket_role.py
new file mode 100644
index 0000000000..b53778558e
--- /dev/null
+++ b/docs/_ext/ticket_role.py
@@ -0,0 +1,38 @@
+"""
+An interpreted text role to link docs to Trac tickets.
+
+To use: :ticket:`XXXXX`
+
+Based on code from psycopg2 by Daniele Varrazzo.
+"""
+from docutils import nodes, utils
+from docutils.parsers.rst import roles
+
+
+def ticket_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    if options is None:
+        options = {}
+    try:
+        num = int(text.replace('#', ''))
+    except ValueError:
+        msg = inliner.reporter.error(
+            "ticket number must be... a number, got '%s'" % text)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+    url_pattern = inliner.document.settings.env.app.config.ticket_url
+    if url_pattern is None:
+        msg = inliner.reporter.warning(
+            "ticket not configured: please configure ticket_url in conf.py")
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+    url = url_pattern % num
+    roles.set_classes(options)
+    node = nodes.reference(rawtext, '#' + utils.unescape(text), refuri=url, **options)
+    return [node], []
+
+
+def setup(app):
+    app.add_config_value('ticket_url', None, 'env')
+    app.add_role('ticket', ticket_role)
diff --git a/docs/conf.py b/docs/conf.py
index 5e89e59d76..d26b1386cd 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,7 +31,12 @@ needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["djangodocs", "sphinx.ext.intersphinx", "sphinx.ext.viewcode"]
+extensions = [
+    "djangodocs",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "ticket_role",
+]
 
 # Spelling check needs an additional module that is not installed by default.
 # Add it only if spelling check is requested so docs can be generated without it.
@@ -349,3 +354,6 @@ epub_cover = ('', 'epub-cover.html')
 
 # If false, no index is generated.
 #epub_use_index = True
+
+# -- ticket options ------------------------------------------------------------
+ticket_url = 'https://code.djangoproject.com/ticket/%s'
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index dbec9921d0..ccbb0ae146 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/docs/internals/contributing/writing-documentation.txt
@@ -192,6 +192,10 @@ __ http://sphinx-doc.org/markup/
 
   To link, use ``:djadminopt:`--traceback```.
 
+* Links to Trac tickets (typically reserved for minor release notes)::
+
+        :ticket:`12345`
+
 .. _documenting-new-features:
 
 Documenting new features
diff --git a/docs/releases/1.6.6.txt b/docs/releases/1.6.6.txt
index f98aaa4176..974adb3a13 100644
--- a/docs/releases/1.6.6.txt
+++ b/docs/releases/1.6.6.txt
@@ -10,36 +10,31 @@ Bugfixes
 ========
 
 * Corrected email and URL validation to reject a trailing dash
-  (`#22579 <http://code.djangoproject.com/ticket/22579>`_).
+  (:ticket:`22579`).
 
-* Prevented indexes on PostgreSQL virtual fields
-  (`#22514 <http://code.djangoproject.com/ticket/22514>`_).
+* Prevented indexes on PostgreSQL virtual fields (:ticket:`22514`).
 
 * Prevented edge case where values of FK fields could be initialized with a
   wrong value when an inline model formset is created for a relationship
-  defined to point to a field other than the PK
-  (`#13794 <https://code.djangoproject.com/ticket/13794>`_).
+  defined to point to a field other than the PK (:ticket:`13794`).
 
 * Restored ``pre_delete``  signals for ``GenericRelation`` cascade deletion
-  (`#22998 <https://code.djangoproject.com/ticket/22998>`_).
+  (:ticket:`22998`).
 
 * Fixed transaction handling when specifying non-default database in
-  ``createcachetable`` and ``flush``
-  (`#23089 <https://code.djangoproject.com/ticket/23089>`_).
+  ``createcachetable`` and ``flush`` (:ticket:`23089`).
 
 * Fixed the "ORA-01843: not a valid month" errors when using Unicode
-  with older versions of Oracle server
-  (`#20292 <https://code.djangoproject.com/ticket/20292>`_).
+  with older versions of Oracle server (:ticket:`20292`).
 
 * Restored bug fix for sending unicode email with Python 2.6.5 and below
-  (`#19107 <https://code.djangoproject.com/ticket/19107>`_).
+  (:ticket:`19107`).
 
 * Prevented ``UnicodeDecodeError`` in ``runserver`` with non-UTF-8 and
-  non-English locale (`#23265 <https://code.djangoproject.com/ticket/23265>`_).
+  non-English locale (:ticket:`23265`).
 
 * Fixed JavaScript errors while editing multi-geometry objects in the OpenLayers
-  widget (`#23137 <https://code.djangoproject.com/ticket/23137>`_,
-  `#23293 <https://code.djangoproject.com/ticket/23293>`_).
+  widget (:ticket:`23137`, :ticket:`23293`).
 
 * Prevented a crash on Python 3 with query strings containing unencoded
-  non-ASCII characters (`#22996 <http://code.djangoproject.com/ticket/22996>`_).
+  non-ASCII characters (:ticket:`22996`).