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 af84ce7e7c..11b6d9afdd 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 215889302b..8b842eff2a 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 `_). + (:ticket:`22579`). -* Prevented indexes on PostgreSQL virtual fields - (`#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 `_). + defined to point to a field other than the PK (:ticket:`13794`). * Restored ``pre_delete`` signals for ``GenericRelation`` cascade deletion - (`#22998 `_). + (:ticket:`22998`). * Fixed transaction handling when specifying non-default database in - ``createcachetable`` and ``flush`` - (`#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 `_). + with older versions of Oracle server (:ticket:`20292`). * Restored bug fix for sending unicode email with Python 2.6.5 and below - (`#19107 `_). + (:ticket:`19107`). * Prevented ``UnicodeDecodeError`` in ``runserver`` with non-UTF-8 and - non-English locale (`#23265 `_). + non-English locale (:ticket:`23265`). * Fixed JavaScript errors while editing multi-geometry objects in the OpenLayers - widget (`#23137 `_, - `#23293 `_). + widget (:ticket:`23137`, :ticket:`23293`). * Prevented a crash on Python 3 with query strings containing unencoded - non-ASCII characters (`#22996 `_). + non-ASCII characters (:ticket:`22996`).