Documentation sprint, April 12 - 13, 2008
We're having a mini-sprint to refactor the documentation this weekend. If you want to help out, join us in #django-sprint.
TODO
Well, a lot. See the checklist below. Also, the notes on contributing to the docsprint. Other things worth doing, not in the checklist:
- (HUGE): break up model documentation (currently all in
topics/db/models and ref/models/querysets into all the various outlined documents in ref/models and topics/db.
- (QUITE LARGE): break up forms documentation from
topics/forms/index into the outlined content in topics/forms and ref/forms.
- Fix up generic views: adapt Chapter 9 of the Django Book (consider this TODO item my permission and license) into
topics/generic-views; remove the intro material from ref/generic-views and just leave the overall reference.
- Add glossary directives for "important" terms. A very small starting list can be found in the contributing documentation, but there's many more candidates for glossary.
- Start looking at the generated index (look in
_build/html/genindex.html after running a build) and improving it by adding index directives where appropriate.
- Find code blocks and make sure they're syntax highlighted correctly.
If you choose to do any of these items, remove it from above and add your name/IRC handle below.
Who's doing what
Please indicate what you're working on below so that we can easily keep track.
- jacobkm -- hacking on the build system
cramm -- adding cross-ref targets at the top of documents still missing it.
jcd -- annotating ref/settings with targets.
knmurphy -- moving over topics/templates to ref/templates/builtins and annotating with templatetag/templatefilter directives
yml -- annotating ref/request-response
- jezdez -- adding module specific markup and description units to contrib/*
knmurphy -- moving topics/middleware into ref/middleware
jacobkm -- refactoring faq/ to have correct links
SimonW -- refactoring template docs in to smaller files
jcd -- adding :setting: xrefs through documentation
knmurphy -- moving ref/django-admin.txt to ./howto/custom-management-commands.txt
- yml -- Replace all images (
.. image:: and .. figure:: directives) with local image files -- right now they use absolute URLs to Django's media server. Images should be put in in _static directory next to the document they're used in. For an example, see internals/contributing.txt and the associated internals/_static directory.
Status
Here's where every file stands. Before we can push this into trunk all the files
have to have content and have to have all the Sphinx markup applied. Stuff like
index entries and code highlighting can come later if needed; when this
checklist is full we can push upstream.
| File | Content | Markup
|
| faq/admin.txt | Y | Y
|
| faq/contributing.txt | Y | Y
|
| faq/general.txt | Y | Y
|
| faq/index.txt | Y | Y
|
| faq/install.txt | Y | Y
|
| faq/models.txt | Y | Y
|
| faq/usage.txt | Y | Y
|
| howto/apache-auth.txt | Y | Y
|
| howto/custom-management-commands.txt | Y | Y
|
| howto/custom-model-fields.txt | Y | Y
|
| howto/custom-template-tags.txt | Y | Y
|
| howto/deployment/fastcgi.txt | Y | Y
|
| howto/deployment/index.txt | Y | Y
|
| howto/deployment/modpython.txt | Y | Y
|
| howto/error-reporting.txt | Y | Y
|
| howto/index.txt | |
|
| howto/initial-data.txt | Y | Y
|
| howto/legacy-databases.txt | Y | Y
|
| howto/newforms-migration.txt | |
|
| howto/outputting-csv.txt | Y |
|
| howto/outputting-pdf.txt | Y |
|
| howto/split-models.txt | |
|
| howto/standalone-templates.txt | |
|
| howto/static-files.txt | Y |
|
| howto/url-best-practices.txt | |
|
| internals/contributing.txt | Y | Y
|
| internals/documentation.txt | |
|
| internals/index.txt | |
|
| intro/index.txt | |
|
| intro/install.txt | |
|
| intro/overview.txt | Y |
|
| intro/tutorial01.txt | Y |
|
| intro/tutorial02.txt | Y |
|
| intro/tutorial03.txt | Y |
|
| intro/tutorial04.txt | Y |
|
| intro/whatsnext.txt | |
|
| misc/api-stability.txt | Y |
|
| misc/design-philosophies.txt | Y |
|
| misc/distributions.txt | Y |
|
| misc/index.txt | |
|
| obsolete/admin-css.txt | Y |
|
| obsolete/form-for-model.txt | Y |
|
| obsolete/forms.txt | Y |
|
| obsolete/index.txt | |
|
| obsolete/pagination.txt | |
|
| ref/contrib/admin.txt | |
|
| ref/contrib/auth.txt | |
|
| ref/contrib/contenttypes.txt | Y | Y
|
| ref/contrib/csrf.txt | Y | Y
|
| ref/contrib/databrowse.txt | Y | Y
|
| ref/contrib/flatpages.txt | Y | Y
|
| ref/contrib/formtools/form-preview.txt | Y |
|
| ref/contrib/formtools/form-wizard.txt | Y |
|
| ref/contrib/formtools/index.txt | |
|
| ref/contrib/index.txt | Y |
|
| ref/contrib/localflavor.txt | Y |
|
| ref/contrib/redirects.txt | Y | Y
|
| ref/contrib/sitemaps.txt | Y |
|
| ref/contrib/sites.txt | Y |
|
| ref/contrib/syndication.txt | Y |
|
| ref/contrib/webdesign.txt | Y |
|
| ref/databases.txt | Y |
|
| ref/django-admin.txt | Y |
|
| ref/forms/api.txt | |
|
| ref/forms/fields.txt | |
|
| ref/forms/index.txt | |
|
| ref/forms/widgets.txt | |
|
| ref/generic-views.txt | |
|
| ref/index.txt | |
|
| ref/middleware.txt | Y | Y
|
| ref/models/fields.txt | |
|
| ref/models/index.txt | |
|
| ref/models/instances.txt | |
|
| ref/models/options.txt | |
|
| ref/models/querysets.txt | |
|
| ref/models/relations.txt | |
|
| ref/request-response.txt | Y | Y
|
| ref/settings.txt | Y | Y
|
| ref/templates/api.txt | Y | Y
|
| ref/templates/authors.txt | Y | Y
|
| ref/templates/builtins.txt | Y | Y
|
| ref/templates/index.txt | Y | Y
|
| ref/unicode.txt | Y |
|
| releases/0.95.txt | Y |
|
| releases/0.96.txt | Y |
|
| releases/index.txt | |
|
| topics/auth.txt | |
|
| topics/cache.txt | Y |
|
| topics/db/index.txt | |
|
| topics/db/managers.txt | |
|
| topics/db/models.txt | |
|
| topics/db/queries.txt | |
|
| topics/db/sql.txt | |
|
| topics/db/transactions.txt | Y |
|
| topics/email.txt | Y |
|
| topics/forms/index.txt | |
|
| topics/forms/modelforms.txt | |
|
| topics/http/auth.txt | |
|
| topics/http/generic-views.txt | |
|
| topics/http/index.txt | |
|
| topics/http/middleware.txt | Y |
|
| topics/http/sessions.txt | |
|
| topics/http/shortcuts.txt | Y |
|
| topics/http/urls.txt | |
|
| topics/http/views.txt | |
|
| topics/i18n.txt | Y |
|
| topics/index.txt | |
|
| topics/install.txt | Y |
|
| topics/pagination.txt | Y |
|
| topics/serialization.txt | Y |
|
| topics/settings.txt | Y |
|
| topics/templates.txt | Y | Y
|
| topics/testing.txt | Y |
|