A bunch of cleanups to file documentation. Along the way some references to the old file methods were removed - thanks, varikin.

Fixes #8642.

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

docs/faq/usage.txt

@@ -45,21 +45,24 @@ Django database layer.
 How do I use image and file fields?
 -----------------------------------
 
-Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
+Using a :class:`~django.db.models.FileField` or an 
+:class:`~django.db.models.ImageField` in a model takes a few steps:
 
-    #. In your settings file, define ``MEDIA_ROOT`` as the full path to
+    #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
-       a directory where you'd like Django to store uploaded files. (For
+       full path to a directory where you'd like Django to store uploaded files.
-       performance, these files are not stored in the database.) Define
+       (For performance, these files are not stored in the database.) Define
-       ``MEDIA_URL`` as the base public URL of that directory. Make sure that
+       :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
-       this directory is writable by the Web server's user account.
+       that this directory is writable by the Web server's user account.
 
-    #. Add the ``FileField`` or ``ImageField`` to your model, making sure
+    #. Add the :class:`~django.db.models.FileField` or 
-       to define the ``upload_to`` option to tell Django to which subdirectory
+       :class:`~django.db.models.ImageField` to your model, making sure to 
-       of ``MEDIA_ROOT`` it should upload files.
+       define the :attr:`~django.db.models.FileField.upload_to` option to tell 
+       Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload 
+       files.
 
     #. All that will be stored in your database is a path to the file 
-       (relative to ``MEDIA_ROOT``). You'll most likely want to use the
+       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
-       convenience ``get_<fieldname>_url`` function provided by Django. For
+       convenience :attr:`~django.core.files.File.url` attribute provided by
-       example, if your ``ImageField`` is called ``mug_shot``, you can get the
+       Django. For example, if your :class:`~django.db.models.ImageField` is
-       absolute URL to your image in a template with
+       called ``mug_shot``, you can get the absolute URL to your image in a
-       ``{{ object.get_mug_shot_url }}``.
+       template with ``{{ object.mug_shot.url }}``.

docs/ref/files/file.txt

@@ -12,109 +12,110 @@ The ``File`` object
 
 Django's ``File`` has the following attributes and methods:
 
-``File.path``
+.. attribute:: File.name
-~~~~~~~~~~~~~
 
-The absolute path to the file's location on a local filesystem.
+    The name of file including the relative path from :setting:`MEDIA_ROOT`.
 
-:ref:`Custom file storage systems <howto-custom-file-storage>` may not store
+.. attribute:: File.path
-files locally; files stored on these systems will have a ``path`` of ``None``.
 
-``File.url``
+    The absolute path to the file's location on a local filesystem.
-~~~~~~~~~~~~
 
-The URL where the file can be retrieved. This is often useful in :ref:`templates
+    :ref:`Custom file storage systems <howto-custom-file-storage>` may not store
-<topics-templates>`; for example, a bit of a template for displaying a ``Car``
+    files locally; files stored on these systems will have a ``path`` of
-(see above) might look like::
+    ``None``.
 
-    <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
+.. attribute:: File.url
 
-``File.size``
+    The URL where the file can be retrieved. This is often useful in
-~~~~~~~~~~~~~
+    :ref:`templates <topics-templates>`; for example, a bit of a template for
+    displaying a ``Car`` (see above) might look like:
     
-The size of the file in bytes.
+    .. code-block:: html+django
 
-``File.open(mode=None)``
+        <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
-~~~~~~~~~~~~~~~~~~~~~~~~
 
-Open or reopen the file (which by definition also does ``File.seek(0)``). The
+.. attribute:: File.size
-``mode`` argument allows the same values as Python's standard ``open()``.
 
-When reopening a file, ``mode`` will override whatever mode the file was
+    The size of the file in bytes.
-originally opened with; ``None`` means to reopen with the original mode.
 
-``File.read(num_bytes=None)``
+.. method:: File.open(mode=None)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Read content from the file. The optional ``size`` is the number of bytes to
+    Open or reopen the file (which by definition also does ``File.seek(0)``).
-read; if not specified, the file will be read to the end.
+    The ``mode`` argument allows the same values as Python's standard
+    ``open()``.
 
-``File.__iter__()``
+    When reopening a file, ``mode`` will override whatever mode the file was
-~~~~~~~~~~~~~~~~~~~
+    originally opened with; ``None`` means to reopen with the original mode.
 
-Iterate over the file yielding one line at a time.
+.. method:: File.read(num_bytes=None)
 
-``File.chunks(chunk_size=None)``
+    Read content from the file. The optional ``size`` is the number of bytes to
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    read; if not specified, the file will be read to the end.
 
-Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults
+.. method:: File.__iter__()
-to 64 KB.
 
-This is especially useful with very large files since it allows them to be
+    Iterate over the file yielding one line at a time.
-streamed off disk and avoids storing the whole file in memory.
 
-``File.multiple_chunks(chunk_size=None)``
+.. method:: File.chunks(chunk_size=None)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Returns ``True`` if the file is large enough to require multiple chunks to
+    Iterate over the file yielding "chunks" of a given size. ``chunk_size``
-access all of its content give some ``chunk_size``.
+    defaults to 64 KB.
 
-``File.write(content)``
+    This is especially useful with very large files since it allows them to be
-~~~~~~~~~~~~~~~~~~~~~~~
+    streamed off disk and avoids storing the whole file in memory.
 
-Writes the specified content string to the file. Depending on the storage system
+.. method:: File.multiple_chunks(chunk_size=None)
-behind the scenes, this content might not be fully committed until ``close()``
-is called on the file.
 
-``File.close()``
+    Returns ``True`` if the file is large enough to require multiple chunks to
-~~~~~~~~~~~~~~~~
+    access all of its content give some ``chunk_size``.
 
-Close the file.
+.. method:: File.write(content)
+
+    Writes the specified content string to the file. Depending on the storage
+    system behind the scenes, this content might not be fully committed until
+    ``close()`` is called on the file.
+
+.. method:: File.close()
+
+    Close the file.
 
 Additional ``ImageField`` attributes
 ------------------------------------
 
-``File.width`` and ``File.height``
+.. attribute:: File.width
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
-These attributes provide the dimensions of the image.
+    Width of the image.
+
+.. attribute:: File.height
+
+    Heigght of the image.
 
 Additional methods on files attached to objects
 -----------------------------------------------
 
-Any ``File`` that's associated with an object (as with ``Car.photo``, above)
+.. highlight:: pycon
-will also have a couple of extra methods:
 
-``File.save(name, content, save=True)``
+Any :class:`File` that's associated with an object (as with ``Car.photo``,
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+above) will also have a couple of extra methods:
 
-Saves a new file with the file name and contents provided. This will not replace
+.. method:: File.save(name, content, save=True)
-the existing file, but will create a new file and update the object to point to
-it. If ``save`` is ``True``, the model's ``save()`` method will be called once
-the file is saved. That is, these two lines::
 
-    >>> car.photo.save('myphoto.jpg', contents, save=False)
+    Saves a new file with the file name and contents provided. This will not
-    >>> car.save()
+    replace the existing file, but will create a new file and update the object
+    to point to it. If ``save`` is ``True``, the model's ``save()`` method will
+    be called once the file is saved. That is, these two lines::
     
-are the same as this one line::
+        >>> car.photo.save('myphoto.jpg', contents, save=False)
+        >>> car.save()
     
-    >>> car.photo.save('myphoto.jpg', contents, save=True)
+    are the same as this one line::
     
-Note that the ``content`` argument must be an instance of
+        >>> car.photo.save('myphoto.jpg', contents, save=True)
-:class:`File` or of a subclass of :class:`File`.
     
-``File.delete(save=True)``
+    Note that the ``content`` argument must be an instance of
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+    :class:`File` or of a subclass of :class:`File`.
 
-Remove the file from the model instance and delete the underlying file. The
+.. method:: File.delete(save=True)
-``save`` argument works as above.
+
+    Remove the file from the model instance and delete the underlying file. The
+    ``save`` argument works as above.

docs/ref/models/fields.txt

@@ -415,20 +415,20 @@ A file-upload field. Has one **required** argument:
 .. attribute:: FileField.upload_to
     
     A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
-    setting to determine the output of the ``get_<fieldname>_url()`` helper
+    setting to determine the value of the :attr:`~django.core.files.File.url`
-    function.
+    attribute.
 
     This path may contain `strftime formatting`_, which will be replaced by the
     date/time of the file upload (so that uploaded files don't fill up the given
     directory).
     
-    .. versionadded:: 1.0
+    .. versionchanged:: 1.0
 
     This may also be a callable, such as a function, which will be called to
-    obtain the upload path, including the filename. This callable must be
+    obtain the upload path, including the filename. This callable must be able
-    able to accept two arguments, and return a Unix-style path (with forward
+    to accept two arguments, and return a Unix-style path (with forward slashes)
-    slashes) to be passed along to the storage system. The two arguments that will
+    to be passed along to the storage system. The two arguments that will be
-    be passed are:
+    passed are:
     
         ======================  ===============================================
         Argument                Description                                    
@@ -470,15 +470,15 @@ takes a few steps:
        that this directory is writable by the Web server's user account.
 
     2. Add the :class:`FileField` or :class:`ImageField` to your model, making
-       sure to define the :attr:`~FileField.upload_to` option to tell Django to
+       sure to define the :attr:`~FileField.upload_to` option to tell Django 
-       which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
+       to which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
 
     3. All that will be stored in your database is a path to the file
        (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
-       convenience ``get_<fieldname>_url`` function provided by Django. For
+       convenience :attr:`~django.core.files.File.url` function provided by 
-       example, if your :class:`ImageField` is called ``mug_shot``, you can get
+       Django. For example, if your :class:`ImageField` is called ``mug_shot``, 
-       the absolute URL to your image in a template with ``{{
+       you can get the absolute URL to your image in a template with 
-       object.get_mug_shot_url }}``.
+       ``{{ object.mug_shot.url }}``.
 
 For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
 :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
@@ -488,8 +488,9 @@ day. If you upload a file on Jan. 15, 2007, it will be saved in the directory
 ``/home/media/photos/2007/01/15``.
 
 If you want to retrieve the upload file's on-disk filename, or a URL that refers
-to that file, or the file's size, you can use the ``File.name``, ``File.url``
+to that file, or the file's size, you can use the 
-and ``File.size`` attributes; see :ref:`topics-files`.
+:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url`
+and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`.
 
 Note that whenever you deal with uploaded files, you should pay close attention
 to where you're uploading them and what type of files they are, to avoid
@@ -581,7 +582,7 @@ image. Has two extra optional arguments:
     Name of a model field which will be auto-populated with the height of the
     image each time the model instance is saved.
 
-.. attribute:: ImageField.width_field`
+.. attribute:: ImageField.width_field
 
     Name of a model field which will be auto-populated with the width of the
     image each time the model instance is saved.