Commits

George Notaras committed 3df7ce7

Updated supplemental files

  • Participants
  • Parent commits 3e753c4

Comments (0)

Files changed (10)

File BUGS

-django-middleware-extras Bugs
-========================================================================
-
-In case you encounter any problems, while using django-middleware-extras,
-or have a feature request, feel free to submit a new issue report in our
-issue tracking system at:
-
-    http://www.codetrax.org/projects/django-middleware-extras/issues/new
-
-Bugs or feature requests reported by means other than the issue tracking system
-are silently ignored.
-
-You can view/search existing issues at the following location:
-
-    http://www.codetrax.org/projects/django-middleware-extras/issues
-
-More information about how to use our issue tracking system can be found at:
-
-    http://www.codetrax.org/NewIssueGuidelines

File HELP

-django-middleware-extras Help
-========================================================================
-This file contains detailed information on how to configure and use
-``django-middleware-extras``.
-
-
-Middleware
-==========
-In order to use the provided middleware it is required that you add
-them to the list of the middleware classes your project uses.
-
-Django, by default, uses the following `middleware classes`__::
-
-    MIDDLEWARE_CLASSES = (
-        'django.middleware.common.CommonMiddleware',
-        'django.contrib.sessions.middleware.SessionMiddleware',
-        'django.middleware.csrf.CsrfViewMiddleware',
-        'django.contrib.auth.middleware.AuthenticationMiddleware',
-        'django.contrib.messages.middleware.MessageMiddleware',
-    )
-
-__ http://docs.djangoproject.com/en/dev/ref/settings/#middleware-classes
-
-The middleware classes provided by ``django-context-extras`` are:
-
-1. ReverseProxyHttpsHeadersMiddleware
--------------------------------------
-By default, Django determines whether the web server communicates with the
-clients over the HTTP or HTTPS protocol by checking the value of the ``HTTPS``
-environment variable. If this variable is set to ``on``, then Django's
-``request.is_secure()`` method returns ``True``. This works well, except for
-those cases that the web server (*Reverse Proxy*), that sits between the Django
-application server and the web, communicates with the Django application server
-using the HTTP protocol. In this case, it is impossible for the reverse
-proxy to "transmit" the ``HTTPS`` environment variable to the Django application
-server. So, the only way the reverse proxy can notify the Django application
-server about the protocol (HTTP or HTTPS) it uses to communicate with the
-clients is by sending specific HTTP headers.
-
-By convention several HTTP headers, such as ``X-Forwarded-Protocol``,
-``X-Forwarded-Ssl``, ``Front-End-Https``, are often used for this purpose. The
-problem in this case is that malicious clients can send such headers without
-actually communicating with the reverse proxy over a secure connection.
-Reverse proxies usually do not filter such headers, so the headers finally make
-it to the Django application server. Therefore, if security matters, such
-headers should not be trusted by the application server.
-
-Django-context-extras provides the administrator with the ability to define
-which headers the application server should trust in order to determine whether
-the reverse proxy communicates with the clients over the HTTPS protocol. At
-the same time, the reverse proxy should be configured to send these headers
-to the application server if it actually communicates with the clients over
-HTTPS. It is extremely hard for malicious clients to guess which headers are
-used for the reverse_proxy <-> app_server communication, so this method is
-very secure and effective at the same time.
-
-In order to implement this functionality, you have to do the following
-3 things:
-
-1. Add ``REVERSE_PROXY_HTTPS_HEADERS`` in your project's ``settings.py`` file
-   and add the header_name/header_value pairs that your Django project should
-   trust so as ``request.is_secure()`` to return *True*. For instance::
-
-       REVERSE_PROXY_HTTPS_HEADERS = (
-           ('x-forwarded-ssl', 'on'),
-       )
-
-   Note that **all** these headers must match those the reverse proxy sends.
-
-2. Add the ``ReverseProxyHttpsHeadersMiddleware`` in the list of your project's
-   middleware classes::
-
-       MIDDLEWARE_CLASSES = (
-           ...
-           'context_extras.middleware.ReverseProxyHttpsHeadersMiddleware',
-       )
-
-3. Configure your reverse proxy to send the headers, which you have specified
-   in the REVERSE_PROXY_HTTPS_HEADERS setting, to the Django application server,
-   whenever communication with the clients is done over the HTTPS protocol.
-   Configuring the reverse proxy is out of the scope of this document, so
-   consult the web server's documentation on how to do this.
-
-
-2. SSLRequireMiddleware
------------------------
 django-middleware-extras Installation Instructions
 ========================================================================
-This file contains information on how to download and install
-django-middleware-extras in your system.
+
+This section contains information about how to download and install
+django-middleware-extras in your system. It also contains brief instructions about how
+to build the included documentation.
 
 
 Requirements
-------------
-This application requires Python 2.3 or later, and a functional installation
-of Django. You can obtain Python from http://www.python.org/ and Django from
-http://www.djangoproject.com/.
+============
+
+This application requires Python_ 2.4 or later and a functional installation
+of Django_.
+
+.. _Python: http://python.org
+.. _Django: http://www.djangoproject.com
 
 Detailed information about the minimum supported Django version and other
-Python modules that may be required in order to run this software are
-available in the `requirements.txt` file.
+Python modules that may be required in order to run this software is shown
+below:
+
+.. literalinclude:: ../requirements.txt
+
+This information exists in the ``requirements.txt`` file inside the
+django-middleware-extras distribution package. If ``pip`` is used to install this software,
+then all these dependencies will also be installed, if they are not already
+installed in your system.
 
 
 Download
---------
-You can download the latest django-middleware-extras releases either from the
-project page at the Python Package Index (PyPI):
+========
 
-  * http://pypi.python.org/pypi/django-middleware-extras
+You can download the latest django-middleware-extras releases from the `releases page`_ at
+the *Python Package Index* (PyPI).
 
-Or you can clone the project's public source code repository and then
-check-out any stable release, all of which are tagged:
+.. _`releases page`: http://pypi.python.org/pypi/django-middleware-extras
+
+Alternatively, you can clone the project's public source code repository
+and then check-out any stable release, all of which are tagged::
 
     hg clone https://source.codetrax.org/hgroot/django-middleware-extras
     hg tags
-    hg update 0.1.1
+    hg update 0.1.0
 
 
 Install
--------
-To install django-middleware-extras, use the provided installation script:
+=======
+
+To install django-middleware-extras, use the provided installation script::
 
     python setup.py install
 
-If you have the Python `easy_install` utility available, you can
-also type the following to download and install in one step:
-
-   easy_install -Z django-middleware-extras
-
-(the `-Z` flag is required to force `easy_install` to do a normal
-source install rather than a zipped egg; django-middleware-extras cannot be
-used from a zipped egg install)
-
-Or if you're using `pip`:
+You can install ``django-middleware-extras`` using ``pip``::
 
     pip install django-middleware-extras
 
-Or if you'd prefer you can simply place the `middleware_extras` directory,
-which exists under `src`, somewhere on your Python path, or symlink to it
-from somewhere on your Python path.
+Or use ``easy_install``::
 
+    easy_install -Z django-middleware-extras
+
+Note: the ``-Z`` flag is required to force ``easy_install`` to do a normal
+source install rather than a zipped egg; django-middleware-extras cannot be
+used from a zipped egg install.
+
+Alternatively, you can simply place the ``middleware_extras`` directory,
+which exists under the ``src`` directory, somewhere on your Python path
+or symlink to it from somewhere on your Python path.
+
+Finally, it is also possible to install this application directly from
+the `source code repository`_ using ``pip``::
+
+    pip install -e hg+https://source.codetrax.org/hgroot/django-middleware-extras#egg=django-middleware-extras
+
+The above command will install the latest development release of
+django-middleware-extras.
+
+To install a stable release directly from the `source code repository`_,
+for instance, the ``0.1.0`` release, run the following command::
+
+    pip install -e hg+https://source.codetrax.org/hgroot/django-middleware-extras@0.1.0#egg=django-middleware-extras-0.1.0
+
+Please note that the mercurial_ source control management tool is required
+for this operation.
+
+.. _mercurial: http://mercurial.selenic.com/
+.. _`source code repository`: https://source.codetrax.org/hgroot/django-middleware-extras
+
+
+How to build the documentation
+==============================
+
+This project's documentation is located in source form under the ``docs``
+directory. In order to convert the documentation to a format that is
+easy to read and navigate you need the ``sphinx`` package.
+
+You can install ``sphinx`` using ``pip``::
+
+    pip install sphinx
+
+Or ``easy_install``::
+
+    easy_install sphinx
+
+Once ``sphinx`` is installed, change to the ``docs`` directory, open a shell
+and run the following command::
+
+    make html
+
+This will build a HTML version of the documentation. You can read the
+documentation by opening the following file in any web browser::
+
+    docs/_build/html/index.html
+
 include AUTHORS
-include BUGS
-include HELP
 include INSTALL
 include LICENSE
 include NOTICE
 include README
-include SUPPORT
 include MANIFEST.in
 include requirements.txt
 include setup.cfg
 include setup.py
-recursive-include src/middleware_extras *.py
+recursive-include src/middleware_extras *.py *.json *.mo *.po *.html
+graft docs
 This product includes software developed at:
-  * CodeTRAX (http://www.codetrax.org/)
-  * G-Loaded Journal (http://www.g-loaded.eu/)
+
+* CodeTRAX (http://www.codetrax.org/)
+* G-Loaded Journal (http://www.g-loaded.eu/)
 
 Copyright 2010 George Notaras <gnot [at] g-loaded.eu>
 
 Brand names include, but are not limited to:
 
-  * django-middleware-extras
-  * middleware_extras
-  * CodeTRAX
-  * G-Loaded Journal
+* django-middleware-extras
+* middleware_extras
+* CodeTRAX
+* G-Loaded Journal
 
 The aforementioned names must not appear in the names of products derived from
 this software without prior written permission of George Notaras.
 
 For license information, please read the LICENSE file.
+
+Django is a registered trademark of the Django Software Foundation.
-django-middleware-extras README
+django-middleware-extras
 ========================================================================
-django-middleware-extras provides some extra middleware classes that are
-often needed by Django projects.
 
-Project Development Web Site:
- * https://www.codetrax.org/projects/django-middleware-extras
+| **Author**: `George Notaras <http://www.g-loaded.eu/>`_
+| **Development Web Site**: `django-middleware-extras project <http://www.codetrax.org/projects/django-middleware-extras>`_
+| **Source Code Repository**: `django-middleware-extras source code <https://source.codetrax.org/hgroot/django-middleware-extras>`_
+| **Documentation**: `django-middleware-extras documentation <http://packages.python.org/django-middleware-extras>`_
+| **Downloads**: `django-middleware-extras releases <http://pypi.python.org/pypi/django-middleware-extras>`_
 
-Public Source Code Repository:
- * https://source.codetrax.org/hgroot/django-middleware-extras
+DESCRIPTION_DESCRIPTION_DESCRIPTION
 
+Licensed under the *Apache License version 2.0*. More licensing information
+exists in the license_ section.
 
-How this distribution package is organized
-========================================================================
-The following list outlines the kind of information each of the files of this
-distribution package contains:
 
- * AUTHORS  : List of all authors and contributors.
- * BUGS     : Information about how to file bug reports or ask for new features.
- * HELP     : Instructions on how to use this software.
- * INSTALL  : Information on how to install this application.
- * LICENSE  : The terms of the license that governs your use of this software.
- * NOTICE   : Copyright, trademark, attribution and sponsorship information.
- * SUPPORT  : Information on how to get support for this software.
- * README   : This file.
+Features
+========
 
+- Feature A
+- Feature B
 
-How to read the HELP document
-========================================================================
-The HELP document is written in reStructuredText (rst). Although
-reStructuredText is an easy-to-read plain text markup format, it is
-recommended to convert it to HTML for a better reading experience.
 
-In order to convert this document to HTML you need `docutils`, which
-you can install in your system using `pip`::
+Documentation
+=============
 
-    pip install docutils
+Apart from the `django-middleware-extras Online Documentation`_, more information about the
+installation, configuration and usage of this application may be available
+at the project's wiki_.
 
-Or `easy_install`:
+.. _`django-middleware-extras Online Documentation`: http://packages.python.org/django-middleware-extras
+.. _wiki: http://www.codetrax.org/projects/django-middleware-extras/wiki
 
-    easy_install docutils
 
-Once `docutils` is installed, you can use the `rst2html.py` utility to
-perform the conversion:
+Donations
+=========
 
-    rst2html.py HELP help.html
+This software is released as free-software and provided to you at no cost. However,
+a significant amount of time and effort has gone into developing this software
+and writing this documentation. So, the production of this software has not
+been free from cost. It is highly recommended that, if you use this software
+*in production*, you should consider making a donation.
 
-Then use any web browser to view the exported `help.html` file.
+To make a donation, please visit the CodeTRAX `donations page`_ which contains
+a PayPal_ *donate* button.
+
+Thank you for considering making a donation to django-middleware-extras.
+
+.. _`donations page`: https://source.codetrax.org/donate.html
+.. _PayPal: https://www.paypal.com
+
+
+Bugs and feature requests
+=========================
+
+In case you run into any problems while using this application or think that
+a new feature should be implemented, it is highly recommended you submit_ a new
+report about it at the project's `issue tracker`_.
+
+Using the *issue tracker* is the recommended way to notify the authors about
+bugs or make feature requests. Also, before submitting a new report, please
+make sure you have read the `new issue guidelines`_.
+
+.. _submit: http://www.codetrax.org/projects/django-middleware-extras/issues/new
+.. _`issue tracker`: http://www.codetrax.org/projects/django-middleware-extras/issues
+.. _`new issue guidelines`: http://www.codetrax.org/NewIssueGuidelines
+
+
+Support
+=======
+
+CodeTRAX does not provide support for django-middleware-extras.
+
+You can still get community support at the `Community Support Forums`_:
+
+.. _`Community Support Forums`: http://www.codetrax.org/projects/django-middleware-extras/boards
 
 
 License
-========================================================================
+=======
+
 Copyright 2010 George Notaras <gnot [at] g-loaded.eu>
 
-Licensed under the Apache License, Version 2.0 (the "License");
+Licensed under the *Apache License, Version 2.0* (the "*License*");
 you may not use this file except in compliance with the License.
 
 Unless required by applicable law or agreed to in writing, software
 See the License for the specific language governing permissions and
 limitations under the License.
 
-A copy of the License exists in the product distribution; the LICENSE file.
-For copyright notes please read the NOTICE file.
-
+A copy of the License exists in the product distribution; the *LICENSE* file.
+For copyright and other important notes regarding this release please read
+the *NOTICE* file.

File SUPPORT

-django-middleware-extras Support
-========================================================================
-
-CodeTRAX does not provide support for django-middleware-extras.
-
-You can still get community support at the Community Support Forums:
-
-    http://www.codetrax.org/projects/django-middleware-extras/boards

File requirements.txt

 django-middleware-extras
 Django
+sphinx
 optimize = 1
 
 [bdist_rpm]
-doc_files = AUTHORS BUGS HELP LICENSE NOTICE README SUPPORT
+doc_files = AUTHORS LICENSE NOTICE README docs
 group = Development/Libraries
+
+[build_sphinx]
+source-dir = docs/
+all_files  = 1
 #
 #  This file is part of django-middleware-extras.
 #
-#  django-middleware-extras provides some extra middleware classes that are
-#  often needed by Django projects.
+#  DESCRIPTION_DESCRIPTION_DESCRIPTION
 #
 #  Development Web Site:
 #    - http://www.codetrax.org/projects/django-middleware-extras
 
 from setuptools import setup
 
-from middleware_extras import get_version, long_description
+from middleware_extras import get_version
+
+def read(fname):
+    """Utility function to read the README file."""
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
 
 if __name__=='__main__':
     setup(
         maintainer = 'George Notaras',
         maintainer_email = 'gnot [at] g-loaded.eu',
         url = 'http://www.codetrax.org/projects/django-middleware-extras',
-        description = 'django-middleware-extras provides some extra middleware classes that are often needed by Django projects.',
-        long_description = long_description,
+        description = 'DESCRIPTION_DESCRIPTION_DESCRIPTION',
+        long_description = read('README'),
         download_url = 'https://source.codetrax.org/hgroot/django-middleware-extras',
+        platforms=['any'],
         classifiers = [
             'Development Status :: 4 - Beta',
             'Environment :: Web Environment',
             'Topic :: Software Development :: Libraries :: Python Modules',
         ],
         package_dir = {'': 'src'},
-        packages = ['middleware_extras'],
+        packages = [
+            'middleware_extras',
+            #'middleware_extras.templatetags',
+            #'middleware_extras.management',
+            #'middleware_extras.management.commands',
+        ],
         include_package_data = True,
         #zip_safe = False,
     )