Fixed #13040 -- Added info on where to import File class from to File…

… reference docs, and improved Sphinx formatting. Thanks to stherrien for the report.

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

docs/ref/files/file.txt

@@ -3,100 +3,106 @@ The ``File`` object
 
 .. currentmodule:: django.core.files
 
-.. class:: File(file_object)
-
 ``File`` attributes and methods
 -------------------------------
 
-Django's ``File`` has the following attributes and methods:
+The :mod:`django.core.files` module contains a built-in class for basic file
+handling in Django. The :class:`File` class has the following attributes and
+methods:
+
+.. class:: File(file_object)
 
-.. attribute:: File.name
+    .. attribute:: name
 
-    The name of file including the relative path from :setting:`MEDIA_ROOT`.
+        The name of file including the relative path from :setting:`MEDIA_ROOT`.
 
-.. attribute:: File.path
+    .. attribute:: path
 
-    The absolute path to the file's location on a local filesystem.
+        The absolute path to the file's location on a local filesystem.
 
-    :doc:`Custom file storage systems </howto/custom-file-storage>` may not store
-    files locally; files stored on these systems will have a ``path`` of
-    ``None``.
+        :doc:`Custom file storage systems </howto/custom-file-storage>` may not store
+        files locally; files stored on these systems will have a ``path`` of
+        ``None``.
 
-.. attribute:: File.url
+    .. attribute:: url
 
-    The URL where the file can be retrieved. This is often useful in
-    :doc:`templates </topics/templates>`; for example, a bit of a template for
-    displaying a ``Car`` (see above) might look like:
-
-    .. code-block:: html+django
+        The URL where the file can be retrieved. This is often useful in
+        :doc:`templates </topics/templates>`; for example, a bit of a template for
+        displaying a ``Car`` (see above) might look like:
+
+        .. code-block:: html+django
+
+            <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
 
-        <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
+    .. attribute:: size
 
-.. attribute:: File.size
+        The size of the file in bytes.
 
-    The size of the file in bytes.
+    .. method:: open([mode=None])
 
-.. method:: File.open(mode=None)
+        Open or reopen the file (which by definition also does ``File.seek(0)``).
+        The ``mode`` argument allows the same values as Python's standard
+        ``open()``.
 
-    Open or reopen the file (which by definition also does ``File.seek(0)``).
-    The ``mode`` argument allows the same values as Python's standard
-    ``open()``.
+        When reopening a file, ``mode`` will override whatever mode the file was
+        originally opened with; ``None`` means to reopen with the original mode.
 
-    When reopening a file, ``mode`` will override whatever mode the file was
-    originally opened with; ``None`` means to reopen with the original mode.
+    .. method:: read([num_bytes=None])
 
-.. method:: File.read(num_bytes=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.
 
-    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.
+    .. method:: __iter__()
 
-.. method:: File.__iter__()
+        Iterate over the file yielding one line at a time.
 
-    Iterate over the file yielding one line at a time.
+    .. method:: chunks([chunk_size=None])
 
-.. method:: File.chunks(chunk_size=None)
+        Iterate over the file yielding "chunks" of a given size. ``chunk_size``
+        defaults to 64 KB.
 
-    Iterate over the file yielding "chunks" of a given size. ``chunk_size``
-    defaults to 64 KB.
+        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.
 
-    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.
+    .. method:: multiple_chunks([chunk_size=None])
 
-.. method:: File.multiple_chunks(chunk_size=None)
+        Returns ``True`` if the file is large enough to require multiple chunks to
+        access all of its content give some ``chunk_size``.
 
-    Returns ``True`` if the file is large enough to require multiple chunks to
-    access all of its content give some ``chunk_size``.
+    .. method:: write([content])
 
-.. 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.
 
-    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:: close()
 
-.. method:: File.close()
+        Close the file.
 
-    Close the file.
+.. currentmodule:: django.core.files.images
 
 Additional ``ImageField`` attributes
 ------------------------------------
 
-.. attribute:: File.width
-
-    Width of the image.
+.. class:: ImageFile(file_object)
+
+    .. attribute:: width
+
+        Width of the image.
 
-.. attribute:: File.height
+    .. attribute:: height
 
-    Height of the image.
+        Height of the image.
+
+.. currentmodule:: django.core.files
 
 Additional methods on files attached to objects
 -----------------------------------------------
 
-.. highlight:: pycon
-
 Any :class:`File` that's associated with an object (as with ``Car.photo``,
 above) will also have a couple of extra methods:
 
-.. method:: File.save(name, content, save=True)
+.. method:: File.save(name, content, [save=True])
 
     Saves a new file with the file name and contents provided. This will not
     replace the existing file, but will create a new file and update the object
@@ -113,7 +119,7 @@ above) will also have a couple of extra methods:
     Note that the ``content`` argument must be an instance of
     :class:`File` or of a subclass of :class:`File`.
 
-.. method:: File.delete(save=True)
+.. method:: File.delete([save=True])
 
     Remove the file from the model instance and delete the underlying file. The
     ``save`` argument works as above.