More documentation.

.gitmodules

+[submodule "doc/_themes"]
+	path = doc/_themes
+	url = https://github.com/mitsuhiko/flask-sphinx-themes.git

_themes @ 0269f3d1

+Subproject commit 0269f3d188eaff07c44a800f35f7351f9e0aefb0

doc/api.rst

+API
+===
+
+.. toctree::
+   :maxdepth: 2
+
+   mod_base
+   mod_model
+   mod_form
+   mod_tools
+
+   mod_ext_sqlamodel

doc/conf.py

@@ -91,7 +91,10 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+sys.path.append(os.path.abspath('_themes'))
+
+html_theme = 'flask'
+html_theme_path = ['_themes']
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

doc/index.rst

@@ -10,6 +10,7 @@ Topics
    :maxdepth: 2
 
    quickstart
+   api
 
 
 Indices and tables

doc/mod_base.rst

+``flask.ext.adminex.base``
+==========================
+
+.. automodule:: flask.ext.adminex.base
+
+    Base View
+    ---------
+
+    .. autofunction:: expose
+
+    .. autoclass:: BaseView
+
+    .. automethod:: BaseView.__init__
+    .. automethod:: BaseView.is_accessible
+    .. automethod:: BaseView.render
+
+    Internal
+    --------
+
+    .. automethod:: BaseView.create_blueprint
+
+
+    Default view
+    ------------
+
+    .. autoclass:: AdminIndexView
+
+        .. automethod:: __init__
+
+    Admin
+    -----
+
+    .. autoclass:: Admin
+
+        .. automethod:: __init__
+        .. automethod:: add_view
+        .. automethod:: setup_app
+        .. automethod:: menu

doc/mod_ext_sqlamodel.rst

+``flask.ext.adminex.ext.sqlamodel``
+===================================
+
+.. automodule:: flask.ext.adminex.ext.sqlamodel
+
+    .. autoclass:: ModelView
+
+    Permissions
+    -----------
+
+    .. autoattribute:: BaseModelView.can_create
+    .. autoattribute:: BaseModelView.can_edit
+    .. autoattribute:: BaseModelView.can_delete
+
+    Templates
+    ---------
+
+    .. autoattribute:: BaseModelView.list_template
+    .. autoattribute:: BaseModelView.edit_template
+    .. autoattribute:: BaseModelView.create_template
+
+    Customizations
+    --------------
+
+    .. autoattribute:: BaseModelView.list_columns
+    .. autoattribute:: BaseModelView.rename_columns
+    .. autoattribute:: BaseModelView.sortable_columns
+    .. autoattribute:: BaseModelView.form_columns
+    .. autoattribute:: BaseModelView.form_args
+
+    .. autoattribute:: ModelView.hide_backrefs
+
+    .. autoattribute:: BaseModelView.page_size
+
+    Constructor
+    -----------
+
+    .. automethod:: ModelView.__init__
+
+    Scaffolding
+    -----------
+
+    .. automethod:: ModelView.scaffold_list_columns
+    .. automethod:: ModelView.scaffold_sortable_columns
+    .. automethod:: ModelView.scaffold_form
+
+    Configuration
+    -------------
+
+    .. automethod:: ModelView.get_list_columns
+    .. automethod:: ModelView.get_sortable_columns
+
+    .. automethod:: ModelView.get_create_form
+    .. automethod:: ModelView.get_edit_form
+
+    Data
+    ----
+
+    .. automethod:: ModelView.get_list
+    .. automethod:: ModelView.get_one
+
+    .. automethod:: ModelView.create_model
+    .. automethod:: ModelView.update_model
+    .. automethod:: ModelView.delete_model
+
+    Helpers
+    -------
+
+    .. automethod:: ModelView.create_form
+    .. automethod:: ModelView.edit_form
+    .. automethod:: ModelView.is_sortable
+    .. automethod:: ModelView.prettify_name
+
+    Views
+    -----
+
+    .. automethod:: ModelView.index_view
+    .. automethod:: ModelView.create_view
+    .. automethod:: ModelView.edit_view
+    .. automethod:: ModelView.delete_view
+
+    Internal API
+    ------------
+
+    .. automethod:: ModelView._get_url

doc/mod_form.rst

+``flask.ext.adminex.form``
+==========================
+
+.. automodule:: flask.ext.adminex.form
+
+    .. autoclass:: AdminForm
+
+        .. automethod:: has_file_field

doc/mod_model.rst

+``flask.ext.adminex.model``
+===========================
+
+.. automodule:: flask.ext.adminex.model
+
+    .. autoclass:: BaseModelView
+
+    Permissions
+    -----------
+
+    .. autoattribute:: BaseModelView.can_create
+    .. autoattribute:: BaseModelView.can_edit
+    .. autoattribute:: BaseModelView.can_delete
+
+    Templates
+    ---------
+
+    .. autoattribute:: BaseModelView.list_template
+    .. autoattribute:: BaseModelView.edit_template
+    .. autoattribute:: BaseModelView.create_template
+
+    Customizations
+    --------------
+
+    .. autoattribute:: BaseModelView.list_columns
+    .. autoattribute:: BaseModelView.rename_columns
+    .. autoattribute:: BaseModelView.sortable_columns
+    .. autoattribute:: BaseModelView.form_columns
+    .. autoattribute:: BaseModelView.form_args
+
+    .. autoattribute:: BaseModelView.page_size
+
+    Constructor
+    -----------
+
+    .. automethod:: BaseModelView.__init__
+
+    Scaffolding
+    -----------
+
+    .. automethod:: BaseModelView.scaffold_list_columns
+    .. automethod:: BaseModelView.scaffold_sortable_columns
+    .. automethod:: BaseModelView.scaffold_form
+
+    Configuration
+    -------------
+
+    .. automethod:: BaseModelView.get_list_columns
+    .. automethod:: BaseModelView.get_sortable_columns
+
+    .. automethod:: BaseModelView.get_create_form
+    .. automethod:: BaseModelView.get_edit_form
+
+    Data
+    ----
+
+    .. automethod:: BaseModelView.get_list
+    .. automethod:: BaseModelView.get_one
+
+    .. automethod:: BaseModelView.create_model
+    .. automethod:: BaseModelView.update_model
+    .. automethod:: BaseModelView.delete_model
+
+    Helpers
+    -------
+
+    .. automethod:: BaseModelView.create_form
+    .. automethod:: BaseModelView.edit_form
+    .. automethod:: BaseModelView.is_sortable
+    .. automethod:: BaseModelView.prettify_name
+
+    Views
+    -----
+
+    .. automethod:: BaseModelView.index_view
+    .. automethod:: BaseModelView.create_view
+    .. automethod:: BaseModelView.edit_view
+    .. automethod:: BaseModelView.delete_view
+
+    Internal API
+    ------------
+
+    .. automethod:: BaseModelView._get_url

doc/mod_tools.rst

+``flask.ext.adminex.tools``
+===========================
+
+.. automodule:: flask.ext.adminex.tools
+
+    .. autofunction:: import_module
+    .. autofunction:: import_attribute
+    .. autofunction:: module_not_found
+    .. autofunction:: rec_getattr
+

doc/quickstart.rst

@@ -2,20 +2,16 @@ Quick Start
 ===========
 
 This page gives quick introduction to Flask-AdminEx library. It is assumed that reader has some prior
-knowledge of Flask framework.
+knowledge of `Flask <http://flask.pocoo.org/>`_ framework.
 
 Introduction
 ------------
 
-While developing the library, I had set of goals which should make it very easy to use and won't
-require monkey patching to achieve desired functionality. Here they are:
+While developing the library, I attempted to make it as flexible as possible, so you don't have
+to monkey patch, if you wanted to extend or change existing functionality.
 
-1. It should be flexible
-2. It should be reusable
-3. It should look nice
-
-Library uses one simple, but powerful concept - administrative pieces are grouped by functionality
-into classes with their own view methods.
+Library uses one simple, but powerful concept - administrative pieces are built as classes with
+view methods.
 
 Here is absolutely valid administrative piece::
 
@@ -28,14 +24,18 @@ Here is absolutely valid administrative piece::
         def test(self):
             return render_template('admin/test.html', view=self)
 
+So, how does it help structuring administrative interface? With such building blocks, you're
+implementing reusable functional pieces that are highly customizable.
 
-With this approach, all of OOP concepts apply. You can derive, you can modify behavior, you can do
-whatever you want.
+For example, Flask-AdminEx provides ready-to-use SQLAlchemy model interface. It is implemented as a
+class which accepts two parameters: model and a database session. While it exposes some
+class-level variables which change behavior of the interface (somewhat similar to django.contrib.admin),
+nothing prohibits you from overriding form creation or database access methods or adding more views.
 
 Initialization
 --------------
 
-You must create `Admin` class and associate it with the `Flask` application::
+To start using Admin, you have to create `Admin` class instance and associate it with Flask application::
 
     from flask import Flask
     from flask.ext.adminex import Admin
@@ -48,18 +48,20 @@ You must create `Admin` class and associate it with the `Flask` application::
     app.run()
 
 If you will run this application and will navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_,
-you should see lonely Home page with a navigation bar on top.
+you should see empty "Home" page with a navigation bar on top.
 
 You can change application name by passing `name` parameter to the `Admin` class constructor::
 
     admin = Admin(name='My App')
     admin.setup_app(app)
 
+Name is displayed in the menu section.
+
 
-Adding first view
------------------
+Adding view
+-----------
 
-Now, lets add custom view::
+Now, lets add a view. To do this, you need to derive from `BaseView` class::
 
     from flask import Flask
     from flask.ext.adminex import Admin, BaseView
@@ -94,24 +96,26 @@ If you will refresh 'Hello' administrative page again you should see greeting in
 Authentication
 --------------
 
-By default, administrative interface will be visible to everyone, as Flask-AdminEx does not make
+By default, administrative interface is visible to everyone, as Flask-AdminEx does not make
 any assumptions about authentication system you're using.
 
 If you want to control who can access administrative views and who can not, derive from the
-administrative view class and implement `is_accessible` method::
+administrative view class and implement `is_accessible` method. So, if you use Flask-Login and
+want to expose administrative interface only to logged in users, you can do something like
+this::
 
     class MyView(BaseView):
         def is_accessible(self):
             return login.current_user.is_authenticated()
 
 
-Menu is generated dynamically, so you can implement policy based security, so some users will see
-some of the administrative interface, others won't be able to, etc.
+Menu is generated dynamically, so you can implement policy-based security and conditionally
+allow or disallow access to parts of the administrative interface.
 
 Generating URLs
 ---------------
 
-Internally, these view classes work on top of Flask blueprints, so you can use `url_for` with a dot
+Internally, view classes work on top of Flask blueprints, so you can use `url_for` with a dot
 prefix to get URL to a local view::
 
     class MyView(BaseView):
@@ -158,15 +162,15 @@ Flask-AdminEx comes with built-in SQLAlchemy model administrative interface. It
     # Flask and Flask-SQLAlchemy initialization here
 
     admin = Admin()
-    admin.add_view(ModelBase(User, db.session, name='Users'))
+    admin.add_view(ModelBase(User, db.session))
     admin.setup_app(app)
 
 This will create administrative interface for `User` model with default settings.
 
 If you want to customize model views, you have two options:
 
-1. Change behavior by overriding public properties that control how these views work
-2. Change behavior by overriding view methods
+1. Change behavior by overriding public properties that control how view works
+2. Change behavior by overriding methods
 
 For example, if you want to disable model creation, show only 'login' and 'email' columns in the list view,
 you can do something like this::
@@ -185,6 +189,7 @@ you can do something like this::
     admin.add_view(UserView(db.session))
     admin.setup_app(app)
 
+
 It is very easy to add support for different database backends (Mongo, etc) by inheriting from `BaseModelView`
 class and implementing database-related methods.
 
@@ -195,6 +200,6 @@ Examples
 
 Flask-AdminEx comes with three samples:
 
-- Simple administrative interface with custom administrative views
-- Sample model view interface
-- Flask-Login integration sample
+- `Simple administrative interface <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/simple>`_ with custom administrative views
+- `SQLAlchemy model example <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/sqla>`_
+- `Flask-Login integration example <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/auth>`_

flask_adminex/base.py

@@ -7,6 +7,7 @@ from flask import Blueprint, render_template, url_for, abort
 def expose(url='/', methods=('GET',)):
     """
         Use this decorator to expose views in your view classes.
+
         `url`
             Relative URL for the view
         `methods`

flask_adminex/ext/sqlamodel.py

@@ -65,7 +65,8 @@ class ModelView(BaseModelView):
 
         Usage sample::
 
-            admin = ModelView(User, db.session)
+            admin = Admin()
+            admin.add_view(ModelView(User, db.session))
     """
 
     hide_backrefs = True

flask_adminex/form.py

@@ -2,8 +2,15 @@ from flask.ext import wtf
 
 
 class AdminForm(wtf.Form):
+    """
+        Customized form class.
+    """
+
     @property
     def has_file_field(self):
+        """
+            Return True if form contains at least one FileField.
+        """
         # TODO: Optimize me
         for f in self:
             if isinstance(f, wtf.FileField):

flask_adminex/model.py

@@ -112,7 +112,7 @@ class BaseModelView(BaseView):
     # Various settings
     page_size = 20
     """
-        Page size. You can change it to something you want.
+        Default page size.
     """
 
     def __init__(self, model,
@@ -147,11 +147,18 @@ class BaseModelView(BaseView):
         self.model = model
 
         # Scaffolding
+        self._refresh_cache()
+
+    # Caching
+    def _refresh_cache(self):
+        """
+            Refresh various cached variables.
+        """
         self._list_columns = self.get_list_columns()
         self._sortable_columns = self.get_sortable_columns()
 
-        self._create_form_class = self.scaffold_create_form()
-        self._edit_form_class = self.scaffold_edit_form()
+        self._create_form_class = self.get_create_form()
+        self._edit_form_class = self.get_edit_form()
 
     # Public API
     def scaffold_list_columns(self):
@@ -225,7 +232,7 @@ class BaseModelView(BaseView):
         """
         raise NotImplemented('Please implement scaffold_form method')
 
-    def scaffold_create_form(self):
+    def get_create_form(self):
         """
             Create form class for model creation view.
 
@@ -233,7 +240,7 @@ class BaseModelView(BaseView):
         """
         return self.scaffold_form()
 
-    def scaffold_edit_form(self):
+    def get_edit_form(self):
         """
             Create form class for model editing view.
 

flask_adminex/tools.py

-import sys, traceback
+import sys
+import traceback
 
 
 def import_module(name, required=True):