Merge pull request #26 from plaes/doc-improvements

Some doc improvements (with patch to fix issue #25)

doc/index.rst

@@ -8,7 +8,7 @@ Flask-Admin is simple and extensible administrative interface framework for `Fla
 
    quickstart
    model_guidelines
-   api
+   api/index
 
 
 Indices and tables

doc/quickstart.rst

@@ -242,6 +242,21 @@ you can do something like this::
     admin = Admin(app)
     admin.add_view(MyView(db.session))
 
+Overriding form elements can be a bit trickier, but it is still possible. Here's an example of
+how to set up a form that includes a column named ``status`` that allows only predefined values and
+therefore should use a ``SelectField``::
+
+    from wtforms.fields import SelectField
+
+    class MyView(ModelView):
+        form_overrides = dict(status=SelectField)
+        form_args = dict(
+            # Pass the choices to the `SelectField`
+            status=dict(
+                choices=[(0, 'waiting'), (1, 'in_progress'), (2, 'finished')]
+            ))
+
+
 It is relatively easy to add support for different database backends (Mongo, etc) by inheriting from :class:`~flask.ext.admin.model.BaseModelView`.
 class and implementing database-related methods.
 

flask_admin/base.py

@@ -195,9 +195,9 @@ class BaseView(object):
 
 class AdminIndexView(BaseView):
     """
-        Administrative interface entry page. You can see it by going to the /admin/ URL.
+        Default administrative interface index page when visiting the ``/admin/`` URL.
 
-        You can override this page by passing your own view class to the `Admin` constructor::
+        It can be overridden by passing your own view class to the ``Admin`` constructor::
 
             class MyHomeView(AdminIndexView):
                 @expose('/')
@@ -206,11 +206,12 @@ class AdminIndexView(BaseView):
 
             admin = Admin(index_view=MyHomeView)
 
-        By default, has following rules:
-        1. If name is not provided, will use 'Home'
-        2. If endpoint is not provided, will use 'admin'
-        3. If url is not provided, will use '/admin'
-        4. Automatically associates with static folder.
+        Default values for the index page are following:
+
+        * If name is not provided, 'Home' will be used.
+        * If endpoint is not provided, will use ``admin``
+        * Default URL route is ``/admin``.
+        * Automatically associates with static folder.
     """
     def __init__(self, name=None, category=None, endpoint=None, url=None):
         super(AdminIndexView, self).__init__(name or babel.lazy_gettext('Home'),
@@ -339,25 +340,25 @@ class Admin(object):
 
     def locale_selector(self, f):
         """
-            Install locale selector for current admin instance.
+            Installs locale selector for current ``Admin`` instance.
 
             Example::
 
-                admin = Admin(app)
-
-                @admin.locale_selector
                 def admin_locale_selector():
                     return request.args.get('lang', 'en')
 
-            Another example:
+                admin = Admin(app)
+                admin.locale_selector(admin_locale_selector)
 
-                def admin_locale_selector():
-                    return request.args.get('lang', 'en')
+            It is also possible to use the ``@admin`` decorator::
 
                 admin = Admin(app)
-                admin.locale_selector(admin_locale_selector)
 
-            And if you want to subclass ``Admin``, you can do something like:
+                @admin.locale_selector
+                def admin_locale_selector():
+                    return request.args.get('lang', 'en')
+
+            Or by subclassing the ``Admin``::
 
                 class MyAdmin(Admin):
                     def locale_selector(self):

flask_admin/model/base.py

@@ -93,8 +93,8 @@ class BaseModelView(BaseView):
             class MyModelView(BaseModelView):
                 sortable_columns = ('name', ('user', 'user.username'))
 
-        For SQLAlchemy models, you can pass attribute instead of the string
-        too::
+        When using SQLAlchemy models, model attributes can be used instead
+        of the string::
 
             class MyModelView(BaseModelView):
                 sortable_columns = ('name', ('user', User.username))
@@ -106,7 +106,7 @@ class BaseModelView(BaseView):
         text-only fields are searchable, but it is up for a model
         implementation to make decision.
 
-        For example::
+        Example::
 
             class MyModelView(BaseModelView):
                 searchable_columns = ('name', 'email')
@@ -118,7 +118,7 @@ class BaseModelView(BaseView):
 
         Can contain either field names or instances of :class:`~flask.ext.admin.model.filters.BaseFilter` classes.
 
-        For example:
+        Example::
 
             class MyModelView(BaseModelView):
                 column_filters = ('user', 'email')
@@ -128,7 +128,7 @@ class BaseModelView(BaseView):
     """
         Form class. Override if you want to use custom form for your model.
 
-        For example:
+        For example::
 
             class MyForm(wtf.Form):
                 pass
@@ -137,12 +137,26 @@ class BaseModelView(BaseView):
                 form = MyForm
     """
 
+    form_args = None
+    """
+        Dictionary of form field arguments. Refer to WTForms documentation for
+        list of possible options.
+
+        Example::
+
+            class MyModelView(BaseModelView):
+                form_args = dict(
+                    name=dict(label='First Name', validators=[wtf.required()])
+                )
+    """
+
+
     form_columns = None
     """
         Collection of the model field names for the form. If set to `None` will
         get them from the model.
 
-        For example:
+        Example::
 
             class MyModelView(BaseModelView):
                 list_columns = ('name', 'email')
@@ -158,19 +172,6 @@ class BaseModelView(BaseView):
                 excluded_form_columns = ('last_name', 'email')
     """
 
-    form_args = None
-    """
-        Dictionary of form field arguments. Refer to WTForm documentation for
-        list of possible options.
-
-        Example::
-
-            class MyModelView(BaseModelView):
-                form_args = dict(
-                    name=dict(label='First Name', validators=[wtf.required()])
-                )
-    """
-
     form_overrides = None
     """
         Dictionary of form column overrides.