README.rst
1Flask-Admin
2===========
3
4The project was recently moved into its own organization. Please update your
5references to *git@github.com:flask-admin/flask-admin.git*.
6
7.. image:: https://d322cqt584bo4o.cloudfront.net/flask-admin/localized.svg
8 :target: https://crowdin.com/project/flask-admin
9
10.. image:: https://travis-ci.org/flask-admin/flask-admin.svg?branch=master
11 :target: https://travis-ci.org/flask-admin/flask-admin
12
13Introduction
14------------
15
16Flask-Admin is a batteries-included, simple-to-use `Flask <http://flask.pocoo.org/>`_ extension that lets you
17add admin interfaces to Flask applications. It is inspired by the *django-admin* package, but implemented in such
18a way that the developer has total control of the look, feel and functionality of the resulting application.
19
20Out-of-the-box, Flask-Admin plays nicely with various ORM's, including
21
22- `SQLAlchemy <http://www.sqlalchemy.org/>`_,
23
24- `MongoEngine <http://mongoengine.org/>`_,
25
26- `pymongo <http://api.mongodb.org/python/current/>`_ and
27
28- `Peewee <https://github.com/coleifer/peewee>`_.
29
30It also boasts a simple file management interface and a `redis client <http://redis.io/>`_ console.
31
32The biggest feature of Flask-Admin is flexibility. It aims to provide a set of simple tools that can be used for
33building admin interfaces of any complexity. So, to start off with you can create a very simple application in no time,
34with auto-generated CRUD-views for each of your models. But then you can go further and customize those views & forms
35as the need arises.
36
37Flask-Admin is an active project, well-tested and production ready.
38
39Examples
40--------
41Several usage examples are included in the */examples* folder. Please add your own, or improve
42on the existing examples, and submit a *pull-request*.
43
44To run the examples in your local environment::
45
46 1. Clone the repository::
47
48 git clone https://github.com/flask-admin/flask-admin.git
49 cd flask-admin
50
51 2. Create and activate a virtual environment::
52
53 virtualenv env -p python3
54 source env/bin/activate
55
56 3. Install requirements::
57
58 pip install -r examples/sqla/requirements.txt
59
60 4. Run the application::
61
62 python examples/sqla/run_server.py
63
64Documentation
65-------------
66Flask-Admin is extensively documented, you can find all of the documentation at `https://flask-admin.readthedocs.io/en/latest/ <https://flask-admin.readthedocs.io/en/latest/>`_.
67
68The docs are auto-generated from the *.rst* files in the */doc* folder. So if you come across any errors, or
69if you think of anything else that should be included, then please make the changes and submit them as a *pull-request*.
70
71To build the docs in your local environment, from the project directory::
72
73 tox -e docs-html
74
75And if you want to preview any *.rst* snippets that you may want to contribute, go to `http://rst.ninjs.org/ <http://rst.ninjs.org/>`_.
76
77Installation
78------------
79To install Flask-Admin, simply::
80
81 pip install flask-admin
82
83Or alternatively, you can download the repository and install manually by doing::
84
85 git clone git@github.com:flask-admin/flask-admin.git
86 cd flask-admin
87 python setup.py install
88
89Tests
90-----
91Test are run with *nose*. If you are not familiar with this package you can get some more info from `their website <https://nose.readthedocs.io/>`_.
92
93To run the tests, from the project directory, simply::
94
95 pip install -r requirements-dev.txt
96 nosetests
97
98You should see output similar to::
99
100 .............................................
101 ----------------------------------------------------------------------
102 Ran 102 tests in 13.132s
103
104 OK
105
106For all the tests to pass successfully, you'll need Postgres & MongoDB to be running locally. For Postgres::
107
108 > psql postgres
109 CREATE DATABASE flask_admin_test;
110 \q
111
112 > psql flask_admin_test
113 CREATE EXTENSION postgis;
114 CREATE EXTENSION hstore;
115
116You can also run the tests on multiple environments using *tox*.
117
1183rd Party Stuff
119---------------
120
121Flask-Admin is built with the help of `Bootstrap <http://getbootstrap.com/>`_, `Select2 <https://github.com/ivaynberg/select2>`_
122and `Bootswatch <http://bootswatch.com/>`_.
123
124If you want to localize your application, install the `Flask-BabelEx <https://pypi.python.org/pypi/Flask-BabelEx>`_ package.
125
126You can help improve Flask-Admin's translations through Crowdin: https://crowdin.com/project/flask-admin
127
