Skeleton for starting a new Flask extension according to best practices:
- Proper Python packaging including best practice for how to provide versioning.
- Examples of unit tests and doc tests.
- Examples of user and API documentation.
- Example of Flask extension class.
- Documentation using Sphinx and with the default Flask theme.
- Test coverage and documentation coverage.
- Travis CI configuration with support for coveralls (test coverage reporting).
- Python 2.6, 2.7 and Python 3.3 compatibility using six library and easy testing via Tox.
To start your new Flask extension:
git clone https://github.com/inveniosoftware/flask-ext-skeleton.git flask-<newname>
cd flask-<newname>
rm -Rf docs/_themes/
# Search and replace
git ls-files | grep -v docs/_themes | xargs sed -i -e 's/YourExt/<NewName>/g'
git ls-files | grep -v docs/_themes | xargs sed -i -e 's/yourext/<newname>/g'
# Rename extension
mv flask_yourext flask_<newname>
# Remove this README, and replace with your extension.
rm README.rst
mv README-YourExt.rst README.rst
# Remove old git repository
rm -Rf .git .gitmodules
# Create new git repository
git init .
git a -A
git submodule add https://github.com/mitsuhiko/flask-sphinx-themes docs/_themes/
git ci -m "Initial commit"
# List files you need to edit
git grep CHANGEME
Here is a quick overview over what you can do locally with your newly created extension:
$ mkvirtualenv flask-newname
(flask-newname)$ pip install Sphinx coverage
(flask-newname)$ python setup.py develop
# Run unit tests
(flask-newname)$ python setup.py test
# Run unit tests with test coverage
(flask-newname)$ source run-tests.sh
# Doc tests
(flask-newname)$ python setup.py build_sphinx -b doctest
# Build documentation (docs/_build/html/index.html)
(flask-newname)$ python setup.py build_sphinx
# Documentation coverage
(flask-newname)$ python setup.py build_sphinx -b coverage && cat docs/_build/coverage/python.txt
# Run unit and doc tests in Python 2.6, Python 2.7 and Python 3.3
(flask-newname)$ tox
The default extension include examples of additional package and modules (apackage and amodule). To remove them, simply delete them and update setup.py, docs/userguide.rst and docs/api.rst.
Running the tests are as simple as: :
python setup.py test
or (to also show test coverage) :
source run-tests.sh
Copyright (C) 2014 CERN.
Flask-YourExt is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Flask-YourExt is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Flask-YourExt; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
In applying this licence, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction.