Developing Fanstatic¶
You want to contribute to Fanstatic? Great!
Please talk to us our on our mailing list about your plans!
Sources¶
Fanstatic’s source code is maintained on GitHub: https://github.com/fanstatic/fanstatic
You can check out fanstatic using Git.
Feel free to fork Fanstatic on Github if you want to hack on it, and send us a pull request when you want us to merge your improvements.
Development install of Fanstatic¶
Fanstatic requires Python 2.7. We believe that the Fanstatic development installation is a good example of how to install a lot of useful tools into a project’s sandbox automatically; read on.
To install Fanstatic for development, first check it out, run buildout bootstrap from a virtualenv, and run buildout:
$ bin/buildout
This uses Buildout. The buildout process will download and install all dependencies for Fanstatic, including development tools.
Don’t worry, that’s all you need to know about buildout to get going
– you only need to run bin/buildout
again if something changes in
Fanstatic’s buildout.cfg
or setup.py
.
The -d
option is to instruct buildout to use Distribute instead
of Setuptools and is optional.
Tests¶
To run the tests:
$ bin/py.test
This uses py.test. We love tests, so please write some if you want
to contribute. There are many examples of tests in the test_*.py
modules.
Test coverage¶
To get a test coverage report:
$ bin/py.test --cov fanstatic
To get a report with more details:
bin/py.test --cov-report html --cov fanstatic
The results will be stored in a subdirectory htmlcov
. You can point
a web browser to its index.html
to get a detailed coverage report.
pyflakes¶
To run pyflakes, you can type:
$ bin/pyflakes fanstatic
Building the documentation¶
To build the documentation using Sphinx:
$ bin/sphinxbuilder
If you use this command, all the dependencies will have been set up
for Sphinx so that the API documentation can be automatically
extracted from the Fanstatic source code. The docs source is in
doc
, the built documentation will be available in
doc/_build/html
.
Python with Fanstatic on the sys.path¶
It’s often useful to have a project and its dependencies available for import on a Python prompt for experimentation:
$ bin/devpython
You can now import fanstatic:
>>> import fanstatic
You can also run your own scripts with this custom interpreter if you like:
$ bin/devpython somescript.py
This can be useful for quick experimentation. When you want to use
Fanstatic in your own projects you would normally include it in your
project’s setup.py
dependencies instead.
Releases¶
The buildout also installs zest.releaser which can be used to make
automatic releases to PyPI (using bin/fullrelease
).
Pre-packaged libraries¶
If you want to make an existing JS library into a fanstatic package, use the
fanstatic paster template from the fanstatictemplate
package.
The pre-packaged libraries live in the https://github.com/fanstatic account.
In order to add a new library, ask one of the fanstatic administrators to create
a repository for you. In the new repository, run fanstatictemplate
and
push your changes.
Register the newly created package on PyPI and add the fanstatic administrators (currently faassen, jw and janjaapdriessen) as owners. After that, add your library to the list of Pre-packaged libraries.