Change API Ref Docs

[Adam Nelson]

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.

[Malcolm Tredinnick]

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.

[Adam Nelson]

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

[Adam Nelson]

#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.

[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.

[Gary Wilson]

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

[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.