Refs #98 - Workaround documentation.

INSTALL

@@ -7,28 +7,70 @@ Install
    If you want to install a development environment, please see
    :doc:`/contributing`.
 
-System requirements:
 
-* Python version 2.7
+************
+Requirements
+************
 
-Install the package with your favorite Python installer. As an example, with
-pip:
-
-.. code:: sh
-
-   pip install django-downloadview
+`django-downloadview` has been tested with Python version 2.7, 3.3 and 3.4.
 
 Installing `django-downloadview` will automatically trigger the installation of
 the following requirements:
 
 .. literalinclude:: /../setup.py
    :language: python
-   :lines: 39
+   :start-after: BEGIN requirements
+   :end-before: END requirements
 
-.. note::
 
-   Since version 1.1, django-downloadview requires Django>=1.5, which provides
-   :py:class:`~django.http.StreamingHttpResponse`.
+************
+As a library
+************
+
+In most cases, you will use `django-downloadview` as a dependency of another
+project. In such a case, you should add `django-downloadview` in your main
+project's requirements. Typically in :file:`setup.py`:
+
+.. code:: python
+
+   from setuptools import setup
+
+   setup(
+       install_requires=[
+           'django-downloadview',
+           #...
+       ]
+       # ...
+   )
+
+Then when you install your main project with your favorite package manager
+(like `pip`_), `django-downloadview` and its recursive dependencies will
+automatically be installed.
+
+
+**********
+Standalone
+**********
+
+You can install `django-downloadview` with your favorite Python package
+manager. As an example with `pip`_:
+
+.. code:: sh
+
+   pip install django-downloadview
+
+
+*****
+Check
+*****
+
+Check `django-downloadview` has been installed:
+
+.. code:: sh
+
+   python -c "import django_downloadview;print(django_downloadview.__version__)"
+
+You should get installed `django-downloadview`'s version.
 
 
 .. rubric:: Notes & references
@@ -41,5 +83,6 @@ the following requirements:
 
 .. target-notes::
 
+.. _`pip`: https://pip.pypa.io/
 .. _`django-downloadview's bugtracker`:
    https://github.com/benoitbryon/django-downloadview/issues

README.rst

@@ -2,24 +2,24 @@
 django-downloadview
 ###################
 
-``django-downloadview`` makes it easy to serve files with Django:
+`django-downloadview` makes it easy to serve files with `Django`_:
 
-* you manage files with Django (permissions, search, generation, ...);
+* you manage files with Django (permissions, filters, generation, ...);
 
 * files are stored somewhere or generated somehow (local filesystem, remote
   storage, memory...);
 
-* ``django-downloadview`` helps you stream the files with very little code;
+* `django-downloadview` helps you stream the files with very little code;
 
-* ``django-downloadview`` helps you improve performances with reverse proxies,
-  via mechanisms such as Nginx's X-Accel.
+* `django-downloadview` helps you improve performances with reverse proxies,
+  via mechanisms such as Nginx's X-Accel or Apache's X-Sendfile.
 
 
 *******
 Example
 *******
 
-Let's serve a file stored in a FileField of some model:
+Let's serve a file stored in a file field of some model:
 
 .. code:: python
 
@@ -45,3 +45,6 @@ Resources
 * Bugtracker: https://github.com/benoitbryon/django-downloadview/issues
 * Continuous integration: https://travis-ci.org/benoitbryon/django-downloadview
 * Roadmap: https://github.com/benoitbryon/django-downloadview/milestones
+
+
+.. _`Django`: https://djangoproject.com

demo/README.rst

@@ -49,7 +49,7 @@ Execute:
    make runserver
 
 It installs and runs the demo server on localhost, port 8000. So have a look
-at http://localhost:8000/
+at ``http://localhost:8000/``.
 
 .. note::
 

demo/demoproject/settings.py

@@ -59,7 +59,7 @@ INSTALLED_APPS = (
 )
 
 
-# Middlewares.
+# BEGIN middlewares
 MIDDLEWARE_CLASSES = [
     'django.middleware.common.CommonMiddleware',
     'django.contrib.sessions.middleware.SessionMiddleware',
@@ -68,19 +68,27 @@ MIDDLEWARE_CLASSES = [
     'django.contrib.messages.middleware.MessageMiddleware',
     'django_downloadview.SmartDownloadMiddleware'
 ]
+# END middlewares
 
 
 # Specific configuration for django_downloadview.SmartDownloadMiddleware.
+# BEGIN backend
 DOWNLOADVIEW_BACKEND = 'django_downloadview.nginx.XAccelRedirectMiddleware'
+# END backend
 """Could also be:
 DOWNLOADVIEW_BACKEND = 'django_downloadview.apache.XSendfileMiddleware'
 DOWNLOADVIEW_BACKEND = 'django_downloadview.lighttpd.XSendfileMiddleware'
 """
+
+# BEGIN rules
 DOWNLOADVIEW_RULES = [
     {
         'source_url': '/media/nginx/',
         'destination_url': '/nginx-optimized-by-middleware/',
     },
+]
+# END rules
+DOWNLOADVIEW_RULES += [
     {
         'source_url': '/media/apache/',
         'destination_dir': '/apache-optimized-by-middleware/',

docs/about/vision.txt

@@ -19,8 +19,8 @@ optimizations.
 
    * :doc:`/about/alternatives`
    * `roadmap
-     <https://github.com/benoitbryon/django-downloadview/issues/milestones>`_
+     <https://github.com/benoitbryon/django-downloadview/milestones>`_
 
 .. target-notes::
 
-.. _`Django`: https://django-project.com
+.. _`Django`: https://djangoproject.com

docs/files.txt

@@ -105,7 +105,7 @@ VirtualFile
 BytesIteratorIO
 ===============
 
-.. autoclass:: ~django_downloadview.io.BytesIteratorIO
+.. autoclass:: django_downloadview.io.BytesIteratorIO
    :members:
    :undoc-members:
    :show-inheritance:
@@ -115,7 +115,7 @@ BytesIteratorIO
 TextIteratorIO
 ==============
 
-.. autoclass:: ~django_downloadview.io.TextIteratorIO
+.. autoclass:: django_downloadview.io.TextIteratorIO
    :members:
    :undoc-members:
    :show-inheritance:

docs/overview.txt

@@ -4,14 +4,14 @@ Overview, concepts
 
 Given:
 
-* you manage files with Django (permissions, search, generation, ...)
+* you manage files with Django (permissions, filters, generation, ...)
 
 * files are stored somewhere or generated somehow (local filesystem, remote
   storage, memory...)
 
 As a developer, you want to serve files quick and efficiently.
 
-Here is an overview of ``django-downloadview``'s answer...
+Here is an overview of `django-downloadview`'s answer...
 
 
 ************************************
@@ -23,9 +23,8 @@ Choose the generic view depending on the file you want to serve:
 * :doc:`/views/object`: file field in a model;
 * :doc:`/views/storage`: file in a storage;
 * :doc:`/views/path`: absolute filename on local filesystem;
-* :doc:`/views/http`: URL (the resource is proxied);
-* :doc:`/views/virtual`: bytes, text, :class:`~StringIO.StringIO`, generated
-  file...
+* :doc:`/views/http`: file at URL (the resource is proxied);
+* :doc:`/views/virtual`: bytes, text, file-like objects, generated files...
 
 
 *************************************************
@@ -67,14 +66,15 @@ Learn more about available file wrappers in :doc:`files`.
 Middlewares convert DownloadResponse into ProxiedDownloadResponse
 *****************************************************************
 
-Before WSGI application use file wrapper to load file contents, middlewares
-(or decorators) are given the opportunity to capture
+Before WSGI application use file wrapper and actually use file contents,
+middlewares or decorators) are given the opportunity to capture
 :class:`~django_downloadview.response.DownloadResponse` instances.
 
 Let's take this opportunity to optimize file loading and streaming!
 
 A good optimization it to delegate streaming to a reverse proxy, such as
-`nginx`_ via `X-Accel`_ internal redirects.
+`nginx`_ via `X-Accel`_ internal redirects. This way, Django doesn't load file
+content in memory.
 
 `django_downloadview` provides middlewares that convert
 :class:`~django_downloadview.response.DownloadResponse` into

docs/settings.txt

@@ -2,23 +2,22 @@
 Configure
 #########
 
-Here is the list of settings used by `django-downloadview`.
+Here is the list of Django settings for `django-downloadview`.
 
 
 **************
 INSTALLED_APPS
 **************
 
-There is no need to register this application in your Django's
-``INSTALLED_APPS`` setting.
+There is no need to register this application in ``INSTALLED_APPS``.
 
 
 ******************
 MIDDLEWARE_CLASSES
 ******************
 
-If you plan to setup reverse-proxy optimizations, add
-``django_downloadview.SmartDownloadMiddleware`` to ``MIDDLEWARE_CLASSES``.
+If you plan to setup :doc:`reverse-proxy optimizations </optimizations/index>`,
+add ``django_downloadview.SmartDownloadMiddleware`` to ``MIDDLEWARE_CLASSES``.
 It is a response middleware. Move it after middlewares that compute the
 response content such as gzip middleware.
 
@@ -26,7 +25,8 @@ Example:
 
 .. literalinclude:: /../demo/demoproject/settings.py
    :language: python
-   :lines: 64-71
+   :start-after: BEGIN middlewares
+   :end-before: END middlewares
 
 
 ********************
@@ -43,7 +43,8 @@ Example:
 
 .. literalinclude:: /../demo/demoproject/settings.py
    :language: python
-   :lines: 75
+   :start-after: BEGIN backend
+   :end-before: END backend
 
 See :doc:`/optimizations/index` for a list of available backends (middlewares).
 
@@ -69,7 +70,8 @@ Here is an example containing one rule using keyword arguments:
 
 .. literalinclude:: /../demo/demoproject/settings.py
    :language: python
-   :lines: 80, 81-84, 103
+   :start-after: BEGIN rules
+   :end-before: END rules
 
 See :doc:`/optimizations/index` for details about builtin backends
 (middlewares) and their options.

setup.py

@@ -53,16 +53,20 @@ KEYWORDS = ['file',
             'offload']
 PACKAGES = [NAME.replace('-', '_')]
 REQUIREMENTS = [
+    # BEGIN requirements
     'Django>=1.5',
     'requests',
     'setuptools',
     'six',
+    # END requirements
 ]
-if IS_PYTHON2:
-    REQUIREMENTS.append('mock')
 ENTRY_POINTS = {}
 SETUP_REQUIREMENTS = ['setuptools']
-TEST_REQUIREMENTS = ['tox']
+TEST_REQUIREMENTS = [
+    'tox'
+]
+if IS_PYTHON2:
+    TEST_REQUIREMENTS.append('mock')
 CMDCLASS = {'test': Tox}
 EXTRA_REQUIREMENTS = {
     'test': TEST_REQUIREMENTS,

tox.ini

@@ -33,7 +33,7 @@ deps =
     Sphinx
 commands =
     pip install -e .
-    make --directory=docs SPHINXOPTS='-W' clean {posargs:html doctest}
+    make --directory=docs SPHINXOPTS='-W' clean {posargs:html doctest linkcheck}
 whitelist_externals =
     make