Opened 7 years ago

Closed 5 years ago

#9502 closed (wontfix)

Docs reST xref markup

Reported by: ramiro Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: xref settings :setting: :mod: :class: :attr:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description (last modified by ramiro)

This patch converts all the bare ``SETTING_NAME`` occurrences all over the trunk documentation as of r9330 to proper :setting:`SETTING_NAME` constructs as per http://docs.djangoproject.com/en/dev/internals/documentation/#todo, except for:

  • ref/settings.txt
  • release/*
  • internals/documentation.txt

replacements were performed with a locally modified docs/_ext/literals_to_xrefs.py script.

It applies to the 1.0.X branch as of r9331 as well, with some fuzz:

$ patch -p1 < ../xref-markup-settings-r9330.diff 
patching file docs/faq/admin.txt
patching file docs/faq/models.txt
patching file docs/howto/deployment/fastcgi.txt
patching file docs/internals/contributing.txt
patching file docs/intro/tutorial01.txt
patching file docs/ref/contrib/admin.txt
patching file docs/ref/contrib/comments/settings.txt
patching file docs/ref/contrib/index.txt
patching file docs/ref/databases.txt
patching file docs/ref/django-admin.txt
Hunk #2 succeeded at 164 (offset 4 lines).
Hunk #3 succeeded at 185 with fuzz 1 (offset 4 lines).
Hunk #4 succeeded at 249 (offset 4 lines).
Hunk #5 succeeded at 263 (offset 4 lines).
Hunk #6 succeeded at 312 (offset 4 lines).
Hunk #7 succeeded at 347 (offset 4 lines).
Hunk #8 succeeded at 552 (offset 32 lines).
Hunk #9 succeeded at 656 (offset 32 lines).
Hunk #10 succeeded at 810 (offset 74 lines).
patching file docs/ref/forms/fields.txt
patching file docs/ref/generic-views.txt
patching file docs/ref/request-response.txt
patching file docs/ref/templates/builtins.txt
patching file docs/topics/cache.txt
patching file docs/topics/db/transactions.txt
patching file docs/topics/email.txt
patching file docs/topics/files.txt
patching file docs/topics/http/file-uploads.txt
patching file docs/topics/http/sessions.txt
patching file docs/topics/http/urls.txt
patching file docs/topics/http/views.txt
patching file docs/topics/i18n.txt
patching file docs/topics/templates.txt
patching file docs/topics/testing.txt
Hunk #1 succeeded at 849 (offset -30 lines).

but visual inspection of the patched files shows they are correcly modified and Sphinx generates no warnings when running make html.

Attachments (9)

xref-markup-settings-r9330.diff (45.2 KB) - added by ramiro 7 years ago.
xref-markup-settings-r9435.diff (47.4 KB) - added by ramiro 7 years ago.
Patch updated to apply cleanly to trunk as of r9435
xref-markup-r9475.diff (111.3 KB) - added by ramiro 7 years ago.
Patch update to r9475, applies to trunk and 1.0.X added :mod: and some :class:, :data:, :attr: and :exc: prefixes
t9502-r9526.diff (114.2 KB) - added by ramiro 7 years ago.
Patch updated with a few more settings xrefs, applies cleanly to trunk and 1.0.x as of r9526
t9502-r9729.diff (113.3 KB) - added by ramiro 7 years ago.
Patch upated to apply cleanly after r9727
t9502-1.0.X-r9729.diff (113.7 KB) - added by ramiro 7 years ago.
Patch for 1.0.X branch as of r9729 as the docs contents have started to diverge from trunk.
9502-trunk-r9885.diff (161.0 KB) - added by ramiro 6 years ago.
Patch for trunk, updated to r9885.
9502-1.0.X-r9885.diff (158.3 KB) - added by ramiro 6 years ago.
Patch for 1.0.X branch, updated to r9885
9502-r9891.diff (160.4 KB) - added by ramiro 6 years ago.
Patch for trunk updated to post r9890

Download all attachments as: .zip

Change History (15)

Changed 7 years ago by ramiro

comment:1 Changed 7 years ago by ramiro

  • Description modified (diff)
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 7 years ago by telenieko

  • Triage Stage changed from Unreviewed to Accepted
  • Version changed from SVN to 1.0-beta-1

Changed 7 years ago by ramiro

Patch updated to apply cleanly to trunk as of r9435

comment:3 Changed 7 years ago by ramiro

  • Keywords xref settings :setting: added
  • Version changed from 1.0-beta-1 to SVN

Just attached patch xref-markup-settings-r9435.diff also applies cleanly to 1.0.X branch as of r9437.

comment:4 Changed 7 years ago by ramiro

  • Keywords :mod: :class: :attr: added
  • Summary changed from Settings xref markup for trunk to Docs reST xref markup

Changed 7 years ago by ramiro

Patch update to r9475, applies to trunk and 1.0.X added :mod: and some :class:, :data:, :attr: and :exc: prefixes

Changed 7 years ago by ramiro

Patch updated with a few more settings xrefs, applies cleanly to trunk and 1.0.x as of r9526

Changed 7 years ago by ramiro

Patch upated to apply cleanly after r9727

Changed 7 years ago by ramiro

Patch for 1.0.X branch as of r9729 as the docs contents have started to diverge from trunk.

Changed 6 years ago by ramiro

Patch for trunk, updated to r9885.

Changed 6 years ago by ramiro

Patch for 1.0.X branch, updated to r9885

comment:5 Changed 6 years ago by ramiro

I've updated the patches for trunk and the 1.0.X branch, with a further enhancement: the modified text lines are correctly wrapped up at column 80.

Also, this time I didn't bother to direct Mercurial to generate versions of the patches with the trailing spaces removed. This make them appear bigger than in reality and could make review of the patches a bit harder but a) I see Gary and Russell are doing the same thing when they touch files under docs/ and b) that's the right thing to do anyways.

Changed 6 years ago by ramiro

Patch for trunk updated to post r9890

comment:6 Changed 5 years ago by ramiro

  • Resolution set to wontfix
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.
Back to Top