Python project documentation with Sphinx

This post is an “open post” where I put useful tips & tricks about documentation in Python projects.

Most used inline formatting rules

  • **bold** which render bold
  • *italics* which render italic
  • “inline literal monospace“ which render inline literal monospace
  • `Python <>`_ which render Python



Python development setup


Pip is a package manager for Python packages. The list of more common packages can be found on Python Package Index (PyPI).

To install or remove a package you just need to do

$ pip install <package_name>
$ pip uninstall <package_name>

A cool feature coming with Pip is an easy way to manage “requirements” through a simple list (package name with versions). You can extract that and use it to replicate the environment with these commands:

$ pip freeze > requirements.txt
$ pip install -r requirements.txt


The cool feature this tools gives you it’s the ability to manage completely separated environments to develop in a non-messy environment. This also helps when you got to keep different versions of Python and libs for different projects.

To install it just do

$ pip install virtualenv

To create a new virtual environment just do

$ virtualenv TEST

That command will create a local folder with inside everything need to manage your new separated world. To use that (to install packages in it and run your project inside it) you should do

$ source bin/activate
(TEST) $

With the activate command your shell environment has been manipulated to let you run your python project within this new separated space. Your $PATH has been manipulated to have this virtualenv’s bin/ as first entry and your prompt now displays the name of the environment you’re in.

Now you can go on and install whatever you need with pip.

While inside your new environment your prompt will be modified to display in which environment you are (the “(TEST)” part).

and to exit it just and restore your shell environment just do

(TEST) $ deactivate


This project exploits VirtualEnv adding some other cool stuff and make the day to day work so much easier. The best things you got with this tool are:

  • virtual environments all stored in a single place, not spread around like before
  • wrapper to create, delete, copy and activate virtual environments with tab completion (!)

To install and setup it just do

$ sudo pip install virtualenvwrapper
$ export WORKON_HOME=~/Envs
$ mkdir -p $WORKON_HOME
$ source /usr/bin/

and insert following lines in .bash_rc to have this tools ready next time too

$ export WORKON_HOME=~/Envs
$ source /usr/local/bin/

Now that it’s installed let’s create a new environment

$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools, pip...done.
(env1) $

As you can see that command will also activate the environment. Now you can install whatever package you want with pip as usual. To list all installed packages you can use lssitepackages command.

To switch to another environment or to activate one just use workon (you can use tab to invoke the list of available environments or just issue the command alone to get a plain list)

$ workon
$ workon (press tab)
env1      env2      env3
$ workon env3

To delete a virtual environment just do

$ rmvirtualenv env1

A full list of command can be found here.


IPython (capital ‘i’) it’s a powerful interactive shells that we can use within our preferred IDE (eg Eclipse+PyDev) to get cool features like tab completion (eg for attribute navigation), object exploration, magic functions, etc.

To install it and invoke it just do

$ pip install ipython
$ ipython
Python 2.7.6 (default, Mar 22 2014, 22:59:56)
Type "copyright", "credits" or "license" for more information.

IPython 2.2.0 -- An enhanced Interactive Python.
? -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help -> Python's own help system.
object? -> Details about 'object', use 'object??' for extra details.

In [1]:



How to install and build a custom Zepto library

If you’re searching for a light-weight JavaScript library similar to jQuery to use in your development for mobile hybrid app (i.e. with PhoneGap) then Zepto is your choice! This library it’s really compact, open source (MIT license), weights just 9.2kB and if you already know jQuery (who doesn’t?) Zepto APIs match jQuery ones…

Zepto’s default package contains these modules: zepto, event, ajax, form and ie (check Zepto site for explanations and full list of modules!).

A very cool thing about Zepto is that you can create your own package with only needed modules! To build a custom Zepto library you should have Node.js installed on your system and follow these steps (for linux and OSX):

  • download Zepto source code from Github (i.e. in zip archive)
  • unzip it and open a terminal in that directory (i.e. you should be inside something like ‘/tmp/zepto-master/’)
  • execute following command:
    • npm install
    • npm run-script dist
    • MODULES=”zepto event data” npm run-script dist

…where “zepto event data” is a space-separated list of wanted modules! After this you should find your Zepto custom library (uncompressed, minified and gzipped) inside ‘dist’ directory (i.e. ‘/tmp/zepto-master/dist/’)…

Please note that inside your custom library you can find in the first line a comment with your choosen modules.

Mobile app development with PhoneGap

PhoneGap by Adobe lets you use HTML5 + CSS3 + JS to build apps once and distribute them over multiple platforms (Apple/iOS, Android, Blackberry, WebOS, Windows, Symbian, Bada). Phonegap supports following features in all major platforms:

  • accelerometer
  • camera
  • geolocation
  • network
  • contacts
  • notification
  • storage
  • media
  • file
  • compass (only on recent ones)

(take a look on their page for a full supported features table)

There are also a bunch of tools and plugins that may come in handy.

Integration with third party (facebook, twitter, outlook, calendars, paypal and so on) can be tricky but necessary to interface services that you need to integrate into your app.

Actual version is 3.3.0: its reference documentation is here while support sections helps you in basic operations.

With PhoneGap you’ll be developing html + css + js webapp using libraries like jQuery and jQuery Mobile or Intel’s AppFramework.

As backend you can use any language/framework to feed your application with fresh data. An example is Yii with a plugin (jAPI) that “convert APIs to JSON”.

PhoneGap seems to be ok for simple and line-straight applications. For more complex application it kinda gets in the way. You can overcome problems writing native code: to use it in your app you must write a PhoneGap plugin. Check out this article too. Couple of hints for iOS and Android.

PhoneGap gives you an handy web service to compile your app for all platforms. This service will ask for you digital certificates and passwords to sign apps… this is not very cool.

PhoneGap give you the “Hydration” option for your app: the binary wrapper will look for new versions of the software on startup letting you to push new builds to your users without going through the standard update mechanism! This is convenient!

You can try out PhoneGap for 1 private app for free: basic plan will cost you 10$/month or 50$/month if you subscribe to Adobe Creative Cloude service.

Useful links


In this post I merged things found in other articles: if you want to read all the original posts check these links:

Dealing with timezones

When your creating an application maybe you end up dealing with timezones… there’s a huge black hole waiting for you there! Just one advice: use an existing, consolidated, tested timezones library!

Check out this funny video from Computerphile with Tom Scott: The Problem with Time & Timezones!

Sass logo

SASS or how to DRY your CSS

I’ve read an interesting article introducing SASS.

In short: SASS (Syntactically Awesome StyleSheets) is an extension of CSS that allow you to code and organize your stylesheet using variables, nested rules, mixins and inline imports!

As outlined in the linked post it may appear as an hindrance but it isn’t: actually if your start using it you’re applying the “don’t repeat yourself” (DRY) principle… no more redundant repetition but a more clean and neat set of stylesheets!

…and it’s an open source project!!!

Steps to get started? A few:

  1. install a Sass application or the command line utility to process .scss files
  2. take a look at sass reference
  3. write a .scss file
  4. put it through one of those compiler and you get your css files!

Javascript (jQuery) gallery made easy

When I need to put a fancy gallery in a site my pick i It’s a well documented MIT-licensed jQuery-based gallery that you can download here. You can eventually purchase even more fancy themes!

css transformation easing

With CSS3 you can apply transformation to DOM objects.. you can do a lot of thing but basically you can translate, rotate, scale and skew. One interesting thing I discovered today is how to add a custom “easing” to that transformation: cubic-bezier!

What you have to put in your css is:

-webkit-transition: -webkit-transform .5s cubic-bezier(.82,.2,.89,.3);
   -moz-transition: -moz-transform    .5s cubic-bezier(.82,.2,.89,.3);
    -ms-transition: -ms-transform     .5s cubic-bezier(.82,.2,.89,.3);
     -o-transition: -o-transform      .5s cubic-bezier(.82,.2,.89,.3);

Instead of “cubic-bezier(a,b,c,d)” you can also use a few preset (linear, ease, ease-in, ease-out, ease-in-out).

To figure out which values put in that function you can use this useful site: There you can also compare curves!!!