Merge pull request #1056 from pawl/tweak_documentation

Corrections/tweaks for docs

doc/advanced.rst

@@ -3,7 +3,7 @@
 Advanced Functionality
 ======================
 
-Enabling CSRF Validation
+Enabling CSRF Protection
 ------------------------
 
 To add CSRF protection to the forms that are generated by *ModelView* instances, use the
@@ -16,14 +16,14 @@ SecureForm class in your *ModelView* subclass by specifying the *form_base_class
         form_base_class = SecureForm
 
 SecureForm requires WTForms 2 or greater. It uses the WTForms SessionCSRF class
-to generate the tokens for you, and validate them when the forms are submitted.
+to generate and validate the tokens for you when the forms are submitted.
 
 Localization With Flask-Babelex
 -------------------------------
 
 ****
 
-Flask-Admin comes with translations built-in for several languages.
+Flask-Admin comes with translations for several languages.
 Enabling localization is simple:
 
 #. Install `Flask-BabelEx <http://github.com/mrjoes/flask-babelex/>`_ to do the heavy
@@ -48,13 +48,13 @@ Enabling localization is simple:
                 session['lang'] = request.args.get('lang')
             return session.get('lang', 'en')
 
-   Now, you could try out a French version of the application at: `http://localhost:5000/admin/?lang=fr <http://localhost:5000/admin/?lang=fr>`_.
+Now, you could try a French version of the application at: `http://localhost:5000/admin/?lang=fr <http://localhost:5000/admin/?lang=fr>`_.
 
-Go ahead and add your own logic to the locale selector function. The application could store locale in
-a user profile, cookie, session, etc. And it could interrogate the `Accept-Language`
-header for making the selection automatically.
+Go ahead and add your own logic to the locale selector function. The application can store locale in
+a user profile, cookie, session, etc. It can also use the `Accept-Language`
+header to make the selection automatically.
 
-If the builtin translations are not enough, look at the `Flask-BabelEx documentation <https://pythonhosted.org/Flask-BabelEx/>`_
+If the built-in translations are not enough, look at the `Flask-BabelEx documentation <https://pythonhosted.org/Flask-BabelEx/>`_
 to see how you can add your own.
 
 .. _file-admin:
@@ -64,8 +64,8 @@ Managing Files & Folders
 
 ****
 
-To manage static files, that are not tied to your db model, Flask-Admin comes with
-the FileAdmin plugin. It gives you the ability to upload, delete, rename, etc. You
+To manage static files instead of database records, Flask-Admin comes with
+the FileAdmin plug-in. It gives you the ability to upload, delete, rename, etc. You
 can use it by adding a FileAdmin view to your app::
 
     from flask_admin.contrib.fileadmin import FileAdmin
@@ -87,7 +87,7 @@ Adding A Redis Console
 
 ****
 
-Another plugin that's available, is the Redis Console. If you have a Redis
+Another plug-in that's available is the Redis Console. If you have a Redis
 instance running on the same machine as your app, you can::
 
     from redis import Redis
@@ -113,7 +113,7 @@ file / image uploads that need to be tied to a field in your model.
 WYSIWIG Text Fields
 *******************
 To handle complicated text content, you can use
-`CKEditor <http://ckeditor.com/>`_ by subclassing some of the builtin WTForms
+`CKEditor <http://ckeditor.com/>`_ by subclassing some of the built-in WTForms
 classes as follows::
 
     from wtforms import TextAreaField
@@ -151,20 +151,19 @@ functionality by including the necessary CKEditor javascript on the `create` and
 File & Image Fields
 *******************
 
-Flask-Admin comes with a builtin :meth:`~flask_admin.form.upload.FileUploadField`
+Flask-Admin comes with a built-in :meth:`~flask_admin.form.upload.FileUploadField`
 and :meth:`~flask_admin.form.upload.ImageUploadField`. To make use
-of them, you'll need to specify an upload directory, and add them to the forms in question.
+of them, you'll need to specify an upload directory and add them to the forms in question.
 Image handling also requires you to have `Pillow <https://pypi.python.org/pypi/Pillow/2.8.2>`_
 installed if you need to do any processing on the image files.
 
 Have a look at the example at
 https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms.
 
-If you are using the MongoEngine backend, Flask-Admin supports GridFS-backed image- and file uploads, done through WTForms fields. Documentation can be found
-at :mod:`flask_admin.contrib.mongoengine.fields`.
+If you are using the MongoEngine backend, Flask-Admin supports GridFS-backed image and file uploads through WTForms fields. Documentation can be found at :mod:`flask_admin.contrib.mongoengine.fields`.
 
 If you just want to manage static files in a directory, without tying them to a database model, then
-rather use the handy :ref:`File-Admin<file-admin>` plugin.
+use the :ref:`File-Admin<file-admin>` plug-in.
 
 Managing Geographical Models
 ----------------------------
@@ -172,8 +171,7 @@ Managing Geographical Models
 ****
 
 If you want to store spatial information in a GIS database, Flask-Admin has
-you covered. The GeoAlchemy backend
-extends the SQLAlchemy backend (just as
+you covered. The GeoAlchemy backend extends the SQLAlchemy backend (just as
 `GeoAlchemy <http://geoalchemy-2.readthedocs.org/>`_  extends SQLAlchemy) to give you a pretty and functional map-based
 editor for your admin pages.
 
@@ -188,7 +186,7 @@ Some notable features include:
  - Works with a `Geometry <http://geoalchemy-2.readthedocs.org/en/latest/types.html#geoalchemy2.types.Geometry>`_ SQL field that is integrated with `Shapely <http://toblerity.org/shapely/>`_ objects.
 
 To get started, define some fields on your model using GeoAlchemy's *Geometry*
-field. An then, add model views to your interface using the ModelView class
+field. Next, add model views to your interface using the ModelView class
 from the GeoAlchemy backend, rather than the usual SQLAlchemy backend::
 
     from geoalchemy2 import Geometry
@@ -242,12 +240,12 @@ them one by one. This works well, but it is difficult to customize.
 Starting from version 1.0.7, Flask-Admin supports form rendering rules, to give you fine grained control of how
 the forms for your modules should be displayed.
 
-The basic idea is pretty simple: the customizable rendering rules replace a static macro, so that you can tell
+The basic idea is pretty simple: the customizable rendering rules replace a static macro, so you can tell
 Flask-Admin how each form should be rendered. As an extension, however, the rendering rules also let you do a
-bit more: You can use them to output HTML, call Jinja2 macros, render fields and so on.
+bit more: You can use them to output HTML, call Jinja2 macros, render fields, and so on.
 
-Essentially, form rendering rules abstract the rendering, so that it becomes separate from the form definition. So,
-for example, it no longer matters in which sequence your form fields are defined.
+Essentially, form rendering rules separate the form rendering from the form definition.
+For example, it no longer matters in which sequence your form fields are defined.
 
 To start using the form rendering rules, put a list of form field names into the `form_create_rules`
 property one of your admin views::
@@ -260,7 +258,7 @@ In this example, only three fields will be rendered and `email` field will be ab
 Whenever Flask-Admin sees a string value in `form_create_rules`, it automatically assumes that it is a
 form field reference and creates a :class:`flask_admin.form.rules.Field` class instance for that field.
 
-Lets say we want to display some text between the `email` and `first_name` fields. This can be accomplished by
+Let's say we want to display some text between the `email` and `first_name` fields. This can be accomplished by
 using the :class:`flask_admin.form.rules.Text` class::
 
     from flask_admin.form import rules
@@ -320,7 +318,7 @@ Flask-Admin has limited support for models with multiple primary keys. It only c
 all but one primary keys are foreign keys to another model. For example, model inheritance following
 this convention.
 
-Lets Model a car with its tyres::
+Let's Model a car with its tyres::
 
     class Car(db.Model):
         __tablename__ = 'cars'
@@ -488,7 +486,7 @@ backends) and specific backend documentation, for example
 :class:`~flask_admin.contrib.sqla.ModelView`. There's much more
 than what is displayed in this table.
 
-Overriding The Form Scaffolding
+Overriding the Form Scaffolding
 -------------------------------
 
 ****

doc/introduction.rst

@@ -11,7 +11,7 @@ Getting Started
 Initialization
 --------------
 
-The first step, is to initialise an empty admin interface on your Flask app::
+The first step is to initialize an empty admin interface for your Flask app::
 
     from flask import Flask
     from flask_admin import Admin
@@ -46,12 +46,12 @@ is the SQLAlchemy backend, which you can use as follows::
 
 Straight out of the box, this gives you a set of fully featured *CRUD* views for your model:
 
-    * A `list` view, with support for searching, sorting and filtering and deleting records.
+    * A `list` view, with support for searching, sorting, filtering, and deleting records.
     * A `create` view for adding new records.
     * An `edit` view for updating existing records.
-    * An optional, read-only `detail` view.
+    * An optional, read-only `details` view.
 
-There are many options available for customizing the display and functionality of these builtin views.
+There are many options available for customizing the display and functionality of these built-in views.
 For more details on that, see :ref:`customising-builtin-views`. For more details on the other
 ORM backends that are available, see :ref:`database-backends`.
 
@@ -66,10 +66,10 @@ is that it's just an empty page with a navigation menu. To add some content to t
       <p>Hello world</p>
     {% endblock %}
 
-This will override the default index template, but still give you the builtin navigation menu.
+This will override the default index template, but still give you the built-in navigation menu.
 So, now you can add any content to the index page, while maintaining a consistent user experience.
 
-Authorisation & Permissions
+Authorization & Permissions
 ===========================
 
 ****
@@ -113,7 +113,7 @@ for that user. For an example of using Flask-Login with Flask-Admin, have a look
 at https://github.com/flask-admin/Flask-Admin/tree/master/examples/auth-flask-login.
 
 The main drawback is that you still need to implement all of the relevant login,
-registration and account management views yourself.
+registration, and account management views yourself.
 
 
 Using Flask-Security
@@ -121,18 +121,18 @@ Using Flask-Security
 
 If you want a more polished solution, you could
 use `Flask-Security <https://pythonhosted.org/Flask-Security/>`_,
-which is a higher-level library. It comes with lots of builtin views for doing
+which is a higher-level library. It comes with lots of built-in views for doing
 common things like user registration, login, email address confirmation, password resets, etc.
 
-The only complicated bit, is making the builtin Flask-Security views integrate smoothly with the
+The only complicated bit is making the built-in Flask-Security views integrate smoothly with the
 Flask-Admin templates to create a consistent user experience. To
-do this, you will need to override the builtin Flask-Security templates and have them
+do this, you will need to override the built-in Flask-Security templates and have them
 extend the Flask-Admin base template by adding the following to the top
 of each file::
 
     {% extends 'admin/master.html' %}
 
-Now, you'll need to manually pass in some context variables for the Flask Admin
+Now, you'll need to manually pass in some context variables for the Flask-Admin
 templates to render correctly when they're being called from the Flask-Security views.
 Defining a `security_context_processor` function will take care of this for you::
 
@@ -146,22 +146,21 @@ Defining a `security_context_processor` function will take care of this for you:
 For a working example of using Flask-Security with Flask-Admin, have a look at
 https://github.com/flask-admin/Flask-Admin/tree/master/examples/auth.
 
-The example only uses the builtin `register` and `login` views, but you could follow the same
+The example only uses the built-in `register` and `login` views, but you could follow the same
 approach for including the other views, like `forgot_password`, `send_confirmation`, etc.
 
 .. _customising-builtin-views:
 
-Customising Builtin Views
+Customizing Built-in Views
 =========================
 
 ****
 
-The builtin `ModelView` class is great for getting started quickly. But you'll want
-to configure its functionality
-to suit your particular models. This is done by setting values for the configuration
-attributes that are made available on the `ModelView` class.
+The built-in `ModelView` class is great for getting started quickly. But, you'll want
+to configure its functionality to suit your particular models. This is done by setting
+values for the configuration attributes that are made available in the `ModelView` class.
 
-To specify some global configuration parameters, you can subclass `ModelView`, and then use that
+To specify some global configuration parameters, you can subclass `ModelView` and use that
 subclass when adding your models to the interface::
 
     from flask_admin.contrib.sqla import ModelView
@@ -191,8 +190,8 @@ Or, in much the same way, you can specify options for a single model at a time::
 ------------------------------------
 
 For a complete list of the attributes that are defined, have a look at the
-API documentation for :meth:`~flask_admin.model.BaseModelView`. Here follows
-some of the most commonly used ones:
+API documentation for :meth:`~flask_admin.model.BaseModelView`. Here are
+some of the most commonly used attributes:
 
 To **disable some of the CRUD operations**, set any of these boolean parameters::
 
@@ -201,7 +200,7 @@ To **disable some of the CRUD operations**, set any of these boolean parameters:
     can_delete = False
 
 If your model has too much data to display in the list view, you can **add a read-only
-detail view** by setting::
+details view** by setting::
 
     can_view_details = True
 
@@ -210,18 +209,17 @@ the *column_excludes_list* parameter::
 
     column_exclude_list = ['password', ]
 
-To **make columns searchable**, or to use them for filtering, specify
-a list of column names::
+To **make columns searchable**, or to use them for filtering, specify a list of column names::
 
     column_searchable_list = ['name', 'email']
-    column_filters = ['country', ]
+    column_filters = ['country']
 
 For a faster editing experience, enable **inline editing** in the list view::
 
     column_editable_list = ['name', 'last_name']
 
-Or, have the add & edit forms display inside a **modal window** on the list page, in stead of
-on the dedicated *create* & *edit* pages::
+Or, have the add & edit forms display inside a **modal window** on the list page, instead of
+the dedicated *create* & *edit* pages::
 
     create_modal = True
     edit_modal = True
@@ -251,8 +249,7 @@ To specify **WTForms field arguments**::
         }
     }
 
-Or, to specify arguments to the **WTForms widgets** used to
-render those fields::
+Or, to specify arguments to the **WTForms widgets** used to render those fields::
 
     form_widget_args = {
         'description': {
@@ -274,7 +271,7 @@ To **manage related models inline**::
 
     inline_models = ['post', ]
 
-These inline forms can be customised. Have a look at the API documentation for
+These inline forms can be customized. Have a look at the API documentation for
 :meth:`~flask_admin.contrib.sqla.ModelView.inline_models`.
 
 To **enable csv export** of the model view::
@@ -289,13 +286,13 @@ Adding Your Own Views
 ****
 
 For situations where your requirements are really specific and you struggle to meet
-them with the builtin :class:`~flask_admin.model.ModelView` class, Flask-Admin makes it easy for you to
+them with the built-in :class:`~flask_admin.model.ModelView` class, Flask-Admin makes it easy for you to
 take full control and add your own views to the interface.
 
 Standalone Views
 ----------------
-A set of standalone views, that are not tied to any particular model, can be added by extending the
-:class:`~flask_admin.base.BaseView` class, and defining your own view methods on it. For
+A set of standalone views (not tied to any particular model) can be added by extending the
+:class:`~flask_admin.base.BaseView` class and defining your own view methods. For
 example, to add a page that displays some analytics data from a 3rd-party API::
 
     from flask_admin import BaseView, expose
@@ -307,10 +304,9 @@ example, to add a page that displays some analytics data from a 3rd-party API::
 
     admin.add_view(CustomView(name='Analytics', endpoint='analytics'))
 
-This will add a link to the navbar, from where your view can be accessed. Notice that
+This will add a link to the navbar for your view. Notice that
 it is served at '/', the root URL. This is a restriction on standalone views: at
-the very minimum, each view class needs
-at least one method to serve a view at its root.
+the very minimum, each view class needs at least one method to serve a view at its root.
 
 The `analytics_index.html` template for the example above, could look something like::
 
@@ -322,9 +318,9 @@ The `analytics_index.html` template for the example above, could look something
 By extending the *admin/master.html* template, you can maintain a consistent user experience,
 even while having tight control over your page's content.
 
-Overriding The Builtin Views
+Overriding the Built-in Views
 ----------------------------
-There may be some scenarios where you want most of the builtin ModelView
+There may be some scenarios where you want most of the built-in ModelView
 functionality, but you want to replace one of the default `create`, `edit`, or `list` views.
 For this you could override only the view in question, and all the links to it will still function as you would expect::
 
@@ -341,33 +337,20 @@ For this you could override only the view in question, and all the links to it w
 
         return self.render('create_user.html')
 
-Working With The Builtin Templates
+Working With the Built-in Templates
 ==================================
 
 ****
 
 Flask-Admin uses the `Jinja2 <http://jinja.pocoo.org/docs/>`_ templating engine.
 
-Overriding The Builtin Templates
---------------------------------
-
-To take full control over the style and layout of the admin interface, you can override
-all of the builtin templates. Just keep in mind that the templates will change slightly
-from one version of Flask-Admin to the next, so once you start overriding them, you
-need to take care when upgrading your package version.
-
-To override any of the builtin templates, simply copy them from
-the Flask-Admin source into your project's `templates/admin/` directory.
-As long as the filenames stay the same, the templates in your project directory should
-automatically take precedence over the builtin ones.
-
 .. _extending-builtin-templates:
 
-Extending The Builtin Templates
+Extending the Built-in Templates
 -------------------------------
 
-Rather than overriding the builtin templates completely, you could extend them. This
-could make it simpler for you to upgrade to new Flask Admin versions in future.
+Rather than overriding the built-in templates completely, it's best to extend them. This
+will make it simpler for you to upgrade to new Flask-Admin versions in future.
 
 Internally, the Flask-Admin templates are derived from the `admin/master.html` template.
 The three most interesting templates for you to extend are probably:
@@ -398,10 +381,23 @@ the admin constructor during initialization::
 
     admin = Admin(app, base_template='microblog_master.html')
 
+Overriding the Built-in Templates
+--------------------------------
+
+To take full control over the style and layout of the admin interface, you can override
+all of the built-in templates. Just keep in mind that the templates will change slightly
+from one version of Flask-Admin to the next, so once you start overriding them, you
+need to take care when upgrading your package version.
+
+To override any of the built-in templates, simply copy them from
+the Flask-Admin source into your project's `templates/admin/` directory.
+As long as the filenames stay the same, the templates in your project directory should
+automatically take precedence over the built-in ones.
+
 Available Template Blocks
 *************************
 
-Flask-Admin defines one *base* template at `admin/master.html` that all the other admin templates are derived
+Flask-Admin defines one *base* template at `admin/master.html` that all other admin templates are derived
 from. This template is a proxy which points to `admin/base.html`, which defines
 the following blocks: