Docs updated

docs/developers/forms.rst

@@ -0,0 +1,60 @@
+=====================
+Using Forms in Misago
+=====================
+
+.. note::
+   Purpose of this document is to introduce you to differences and features of forms module available in misago.core.forms package.
+
+   For proper introduction to forums, see `Django documentation <https://docs.djangoproject.com/en/dev/topics/forms/>`_.
+
+
+Misago wraps standard forms library that comes with Django with two extra layers layers of abstraction. First one is `Django-floppyforms <http://django-floppyforms.readthedocs.org/en/latest/>`_ app that allows to use templates to display forms.
+ Thanks to this feature, it's possible to render correct markup that `Bootstrap <getbootstrap.com/css/#forms>`_ requires with minimal amount of efford.
+
+
+Misago Forms Module
+===================
+
+Second layer lies in :py:mod:`misago.core.forms` module that wraps floppyforms. This layer introduces tiny convenience change to forms standard clean and validate behaviour that will save you from some "gotchas" associated with input length validation. Unlike other popular frameworks and solutions, Django does not automatically trim input values received from client before validation, which means user can enter few spaces into text fields instead of "readable" value and such input will pass automatical validation and will need additional cleanup and checks in custom ``clean_`` methods. Because there's good chance your app will have plenty of ``CharField`` fields, such boilerplate can quickly add up.
+
+In :py:mod:`misago.core.forms` you will find three classes:
+
+
+AutoStripWhitespacesMixin
+-------------------------
+
+:py:class:`misago.core.forms.AutoStripWhitespacesMixin`
+
+Small mixin that strips whitespaces from all ``CharField``'s input on form, before its passed further for validation.
+
+If you wish to exclude one or more fields from this behaviour, you may add their names to "autostrip_exclude" attribute::
+
+
+    class MyLargeForm(Form):
+        autostrip_exclude = ['i_wont_be_stripped']
+        i_will_be_stripped = forms.CharField()
+        i_wont_be_stripped = forms.CharField()
+
+
+Form
+----
+
+:py:class:`misago.core.forms.Form`
+
+Wrapper for :py:class:`floppyforms.Form` that uses AutoStripWhitespacesMixin.
+
+
+ModelForm
+---------
+
+:py:class:`misago.core.forms.ModelForm`
+
+Wrapper for :py:class:`floppyforms.ModelForm` that uses AutoStripWhitespacesMixin.
+
+
+Picking Layer
+-------------
+
+Each of namespaces mentioned here, be it :py:mod:`django.forms`, :py:mod:`floppyforms` or :py:mod:`misago.core.forms` imports previous namespace, which means after you import :py:mod:`floppyforms`, you don't have to import :py:mod:`django.forms` too.
+
+When writing custom forms, please avoid using :py:mod:`django.forms`, instead using either :py:mod:`floppyforms` or :py:mod:`floppyforms`.

docs/developers/index.rst

@@ -36,3 +36,4 @@ Following references cover everything you want to know about writing your own ap
    views_errors
    cache_buster
    thread_store
+   forms

docs/developers/views_errors.rst

@@ -13,23 +13,10 @@ To solve this problem you would have to write custom error views and handlers th
 Misago views too have to solve this problem and this reason is why error handling boilerplate is part of framework.
 
 
-Http404
-=======
-
-:py:class:`misago.views.exceptions.Http404`
-
-Misago's Http404 exception subclasses `Django Http404 <https://docs.djangoproject.com/en/dev/topics/http/views/#the-http404-exception>`_, but changes nothing about its implementation and exists simply to delegate 404 error handling to Misago's exceptions handler.
-
-Raise this exception if requested page does not exists or user's permission set shows that he shouldn't know if it exists. If you want to, you can insert custom error message into exception's constructor to be displayed by error page instead of default one.
-
-
-   raise Http404("Requested thread could not be found. Perhaps it was moved or deleted?")
-
-
 OutdatedUrl
 ===========
 
-:py:class:`misago.views.exceptions.OutdatedUrl`
+:py:class:`misago.core.exceptions.OutdatedUrl`
 
 OutdatedUrl exception is special "message" that tells Misago to return `permanent <http://en.wikipedia.org/wiki/HTTP_301>`_ redirection as response instead of intended view.
 
@@ -38,22 +25,10 @@ This exception is raised by view utility that compares link's "slug" part agains
 You should never raise this exception yourself, instead always return proper redirect response from your code.
 
 
-PermissionDenied
-================
-
-:py:class:`misago.views.exceptions.PermissionDenied`
-
-Misago's PermissionDenied exception subclasses `Django PermissionDenied <https://docs.djangoproject.com/en/dev/ref/exceptions/#django.core.exceptions.PermissionDenied>`_, but changes nothing about its implementation and exists simply to delegate 403 error handling to Misago's exceptions handler.
-
-Raise this exception if user knows of requested page or action but has no permission to access or perform it. If you want to, you can insert custom error message into exception's constructor to be displayed by error page instead of default one.
-
-    raise PermissionDenied("This thread is locked. You can't reply to it.")
-
-
 Exception Handler
 =================
 
-:py:mod:`misago.views.exceptions.handler`
+:py:mod:`misago.core.exceptionhandler`
 
 Exception handler is lightweight system that pairs exceptions with special "handler" functions that turn those exceptions into valid HTTP responses that are then served back to client.
 

docs/index.rst

@@ -25,3 +25,4 @@ Table of Contents
    developers/views_errors
    developers/cache_buster
    developers/thread_store
+   developers/forms

misago/core/forms.py

@@ -2,7 +2,7 @@ from floppyforms import *
 from floppyforms import Form as BaseForm, ModelForm as BaseModelForm
 
 
-class AutoStripInputMixin(object):
+class AutoStripWhitespacesMixin(object):
     autostrip_exclude = None
 
     def full_clean(self):
@@ -17,9 +17,9 @@ class AutoStripInputMixin(object):
         return super(AutoStripInputMixin, self).full_clean()
 
 
-class Form(AutoStripInputMixin, BaseForm):
+class Form(AutoStripWhitespacesMixin, BaseForm):
     pass
 
 
-class ModelForm(AutoStripInputMixin, BaseModelForm):
+class ModelForm(AutoStripWhitespacesMixin, BaseModelForm):
     pass