More doc improvements: tweaks to the overview; added admin css documentation from wilson.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@50 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/admin_css.txt

@@ -0,0 +1,181 @@
+======================
+Django Admin CSS Guide
+======================
+
+Django's dynamic admin interface gives you a fully-functional admin for free
+with no hand-coding required. The dynamic admin is designed to be
+production-ready, not just a starting point, so you can use it as-is on a real
+site. While the underlying format of the admin pages is built in to Django, you
+can customize the look and feel by editing the admin stylesheet and images.
+
+Here's a quick and dirty overview some of the main styles and classes used in
+the Django admin CSS.
+
+Modules
+=======
+
+The ``.module`` class is a basic building block for grouping content in the
+admin. It's generally applied to ``div``s or ``fieldset``s. It wraps the content
+group in a box and applies certain styles to the elements within. An ``h2``
+within a ``div.module`` will align to the top of the ``div`` as a header for the
+whole group.
+
+Column Types
+============
+
+The base template for each admin page has a block that defines the column
+structure for the page. This sets a class on the page content area
+(``div#content``) so everything on the page knows how wide it should be. So far
+there are three options available, and one special hybrid option.
+
+colM
+    This is the default column setting for all pages. The "M" stands for "main".
+    Assumes that all content on the page is in one main column
+    (``div#content-main``).
+colMS
+    This is for pages with one main column and a sidebar on the right. The "S"
+    stands for "sidebar". Assumes that main content is in ``div#content-main``
+    and sidebar content is in ``div#content-related``. This is used on the main
+    admin page.
+colSM
+    Same as above, with the sidebar on the left. The source order of the columns
+    doesn't matter.
+colM superwide
+    This is for ridiculously wide pages. Doesn't really work very well for
+    anything but colM. With superwide, you've got 1000px to work with. Don't
+    waste them.
+flex
+    This is for liquid-width pages, such as changelists. Currently only works
+    with single-colum pages (does not combine with ``.colMS`` or ``.colSM``).
+    Form pages should never use ``.flex``.
+
+For instance, you could stick this in a template to make a superwide page::
+
+    {% block coltype %}colM superwide{% endblock %}
+
+or this to make a liquid-width page (note that ``flex`` replaces ``colM``, so
+both classes are not required)::
+
+    {% block coltype %}flex{% endblock %}
+
+Widths
+======
+
+There's a whole mess of classes in the stylesheet for custom pixel widths on
+objects. They come in handy for tables and table cells, if you want to avoid
+using the ``width`` attribute. Each class sets the width to the number of pixels
+in the class, except ``.xfull`` which will always be the width of the column
+it's in. (This helps with tables that you want to always fill the horizontal
+width, without using ``width="100%"`` which makes IE 5's box model cry.)
+
+``'Note:``' Within a ``.flex`` page, the ``.xfull`` class will ``usually`` set
+to 100%, but there are exceptions and still some untested cases.
+
+Available width classes::
+
+    .x50 .x75 .x100 .x150 .x200 .x250 .x300 .x400 .x500 .xfull
+
+Text Styles
+===========
+
+Font Sizes
+----------
+
+Most HTML elements (headers, lists, etc.) have base font sizes in the stylesheet
+based on context. There are three classes are available for forcing text to a
+certain size in any context.
+
+small
+    11px
+tiny
+    10px
+mini
+    9px (use sparingly)
+
+Font Styles and Alignment
+-------------------------
+
+There are also a few styles for styling text.
+
+.quiet
+    Sets font color to light gray. Good for side notes in instructions. Combine
+    with ``.small`` or ``.tiny`` for sheer excitement.
+.help
+    This is a custom class for blocks of inline help text explaining the
+    function of form elements. It makes text smaller and gray, and when applied
+    to ``p``s withing ``.form-row`` elements (see Form Styles below), it will
+    offset the text to align with the form field. Use this for help text,
+    instead of ``small quiet``. It works on ``span``s, but try to put the class
+    on the ``p`` whenever you can.
+.align-left
+    It aligns the text left. Only works on block elements, I think.
+.align-right
+    Are you paying attention?
+.nowrap
+    Keeps text from wrapping. Comes in handy for table headers you want to stay
+    on one line.
+
+Floats and Clears
+-----------------
+
+float-left
+    floats left
+float-right
+    floats right
+clear
+    clears all
+
+Object Tools
+============
+
+Certain actions which apply directly to an object are used in form and
+changelist pages. These appear in a "toolbar" row above the form or changelist,
+to the right of the page. The tools are wrapped in a ``ul`` with the class
+``object-tools``. There are two custom tool types which can be defined with an
+additional class on the ``a`` for that tool. These are ``.addlink`` and
+``.viewsitelink``.
+
+Example from a changelist page::
+
+    <ul class="object-tools"><li><a href="/stories/add/" class="addlink">Add story</a></li></ul>
+
+and from a form page::
+
+    <ul class="object-tools">
+     <li><a href="/history/303/152383/">History</a></li>
+     <li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
+    </ul>
+
+Form Styles
+===========
+
+Fieldsets
+---------
+
+Admin forms are broken up into groups by ``fieldset``s. Each form fieldset
+should have a class ``.module``. Each fieldset should have a header ``h2``
+within the fieldset at the top (except the first group in the form, and in some
+cases where the group of fields doesn't have a logical label).
+
+Each fieldset can also take extra classes in addition to ``.module`` to apply
+appropriate formatting to the group of fields.
+
+.aligned
+    this will align the labels and inputs side by side on the same line.
+.wide
+    used in combination with ``.aligned`` to widen the space available for the labels.
+
+Form Rows
+---------
+
+Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
+with class ``form-row``. If the field in the row is required, a class of
+``required`` should also be added to the ``form-row div``.
+
+Labels
+------
+
+Each form ``label`` and field should be enclosed in a header ``h4``. Any
+explanation or help text should follow this ``h4`` in a ``p`` with class
+``.help``. Form ``label``s should always precede the field, except in the case
+of checkboxes and radio buttons, where the ``input`` should come first.

docs/overview.txt

@@ -1,6 +1,6 @@
-===============
+==================
-Django overview
+Django at a glance
-===============
+==================
 
 Because Django was developed in a fast-paced newsroom environment, it was
 designed to make common Web-development tasks fast and easy. Here's an informal
@@ -17,7 +17,7 @@ Design your model
 =================
 
 Start by describing your database layout in Python code. Django's data-model API
-offers many rich ways of representing your models — so far, it's been
+offers many rich ways of representing your models -- so far, it's been
 solving two years' worth of database-schema problems. Here's a quick example::
 
     class Reporter(meta.Model):
@@ -127,7 +127,7 @@ A dynamic admin interface: It's not just scaffolding -- it's the whole house
 ============================================================================
 
 Once your models are defined, Django can automatically create an administrative
-interface — a Web site that lets authenticated users add, change and
+interface -- a Web site that lets authenticated users add, change and
 delete objects. It's as easy as adding an extra admin attribute to your model
 classes::
 
@@ -183,9 +183,9 @@ requested URL. (If none of them matches, Django calls a special 404 view.) This
 is blazingly fast, because the regular expressions are compiled at load time.
 
 Once one of the regexes matches, Django imports and calls the given view, which
-is a simple Python function. Each view gets passed a request object —
+is a simple Python function. Each view gets passed a request object --
 which contains request metadata and lets you access GET and POST data as simple
-dictionaries — and the values captured in the regex, via keyword
+dictionaries -- and the values captured in the regex, via keyword
 arguments.
 
 For example, if a user requested the URL "/articles/2005/05/39323/", Django
@@ -282,14 +282,14 @@ Here's what the "base" template might look like::
 
 Simplistically, it defines the look-and-feel of the site (with the site's logo),
 and provides "holes" for child templates to fill. This makes a site redesign as
-easy as changing a single file — the base template.
+easy as changing a single file -- the base template.
 
 Note that you don't have to use Django's template system if you prefer another
 system. While Django's template system is particularly well-integrated with
 Django's model layer, nothing forces you to use it. For that matter, you don't
 have to use Django's API, either. You can use another database abstraction
 layer, you can read XML files, you can read files off disk, or anything you
-want. Each piece of Django — models, views, templates — is decoupled
+want. Each piece of Django -- models, views, templates -- is decoupled
 from the next.
 
 This is just the surface
@@ -301,7 +301,7 @@ features:
     * A caching framework that integrates with memcached or other backends.
     * An RSS framework that makes creating RSS feeds as easy as writing a 
       small Python class.
-    * More sexy automatically-generated admin features — this overview barely
+    * More sexy automatically-generated admin features -- this overview barely
       scratched the surface
 
 The next obvious steps are for you to download Django, read the documentation