Opened 16 years ago

Closed 15 years ago

Last modified 15 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: no UI/UX: no

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 15 years ago.

Download all attachments as: .zip

Change History (9)

comment:1 by Malcolm Tredinnick, 16 years ago

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 by Adam Nelson, 16 years ago

Owner: changed from nobody to Adam Nelson

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

comment:3 by Adam Nelson, 15 years ago

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 by Adam Nelson, 15 years ago

Status: newassigned

comment:5 by Adam Nelson, 15 years ago

Triage Stage: AcceptedReady for checkin

by Adam Nelson, 15 years ago

Attachment: ref.diff added

comment:6 by Adam Nelson, 15 years ago

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 by Gary Wilson, 15 years ago

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 by Gary Wilson, 15 years ago

(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