Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#9465 closed (fixed)

Change API Ref Docs

Reported by: adamnelson Owned by: adamnelson
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 adamnelson 6 years ago.

Download all attachments as: .zip

Change History (9)

comment:1 Changed 7 years ago by mtredinnick

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

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 7 years ago by adamnelson

  • Owner changed from nobody to adamnelson

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

comment:3 Changed 6 years ago by adamnelson

  • 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 6 years ago by adamnelson

  • Status changed from new to assigned

comment:5 Changed 6 years ago by adamnelson

  • Triage Stage changed from Accepted to Ready for checkin

Changed 6 years ago by adamnelson

comment:6 Changed 6 years ago by adamnelson

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 6 years ago by gwilson

  • Resolution set to fixed
  • Status changed from assigned to closed

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

comment:8 Changed 6 years ago by gwilson

(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