Opened 8 years ago

Closed 7 years ago

Last modified 7 years ago

#9465 closed (fixed)

Change API Ref Docs

Reported by: Adam Nelson Owned by: Adam Nelson
Component: Documentation Version: 1.0
Severity: Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

Database Docs can be difficult to find

http://docs.djangoproject.com/en/dev/ref/
http://docs.djangoproject.com/en/dev/ref/databases/

Problem

When skimming the reference docs, the different titles for each item are difficult to discern.

Solution

Use simple titles.

I think this is closer to the best list for the entire reference page - in alphabetical order:

  • Databases
  • django-admin.py and manage.py
  • django.contrib
  • Files
  • Forms
  • Middleware
  • Models
  • Request and Response objects
  • Settings
  • Signals
  • Templates
  • Unicode Data
  • Views

Notes

I don't mind doing this if the docs system supports me making changes and somebody else approving them. I'm not sure if that's the case.

Attachments (1)

ref.diff (6.3 KB) - added by Adam Nelson 7 years ago.

Download all attachments as: .zip

Change History (9)

comment:1 Changed 8 years ago by Malcolm Tredinnick

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

Anybody can check out the source and create a patch. Read internals/contributing.txt and internals/documentation.txt first.

Right now, the headings on the index page are created from the titles of the documents themselves and so to get your output merely by reordering, those titles would have to be changed (to something less descriptive than what they are now). Instead, you'll have to tell Sphinx to use a different string for the title and still insert the right cross-reference (how to do this is in the documentation.txt file and the Sphinx documentation).

This change should be consistent across all index.txt files, not just the one you've noticed. This isn't show-stoppingly critical, so we might as well avoid the half-baked solution and make the same change to all the files at once.

comment:2 Changed 8 years ago by Adam Nelson

Owner: changed from nobody to Adam Nelson

Ok, I should have a patch with comments by Monday.

comment:3 Changed 7 years ago by Adam Nelson

Has patch: set

#11570 changes are in here too - but since they are all in one file and extremely minor, I just left them in (let me know if they need to be stripped out). I got rid of unnecessary words in the titles.

comment:4 Changed 7 years ago by Adam Nelson

Status: newassigned

comment:5 Changed 7 years ago by Adam Nelson

Triage Stage: AcceptedReady for checkin

Changed 7 years ago by Adam Nelson

Attachment: ref.diff added

comment:6 Changed 7 years ago by Adam Nelson

Updated diff based on current trunk. It seems like this could trivially be added to milestone:1.2 but I'll leave that to a committer.

comment:7 Changed 7 years ago by Gary Wilson

Resolution: fixed
Status: assignedclosed

(In [11990]) Fixed #9465 -- Simplified API Reference documentation titles for easier lookup and made first-level heading styles consistent. Thanks, adamnelson.

comment:8 Changed 7 years ago by Gary Wilson

(In [11991]) [1.1.X] Fixed #9465 -- Simplified API Reference documentation titles for easier lookup and made first-level heading styles consistent. Thanks, adamnelson.

Backport of r11990 from trunk.

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