Integrating Pylons into Sphinx

Sphinx is now able to build a webapp and serve the documentation. Let’s take a look at how it works, step by step (I assume that you got Sphinx from my repo on Bitbucket installed):

1. Start a new Sphinx project:

$ mkdir sphinx-project
$ cd sphinx-project/
$ sphinx-quickstart
[…usual sphinx-quickstart questions…]

2. Our documentation is empty as for now, but still we can build a webapp which will serve the default documentation template:

$ make webapp
Build finished. The webapp HTML pages are in _build/webapp.

3. Run the server:

$ cd _build/webapp/WebAppProject/
$ paster serve –reload development.ini
Starting subprocess with file monitor
Starting server in PID 6119.
serving on

OK, so there it goes!

Let’s take a look:


The usual way of starting a Pylons project is (in my project I import CreateDistroCommand class from paste.script.create_distro instead of executing paster):

$ paster create –template=pylons TemplateDemo

Paster then asks two questions to the user:

Enter template_engine (mako/genshi/jinja2/etc: Template language) [‘mako’]:
Enter sqlalchemy (True/False: Include SQLAlchemy 0.5 configuration) [False]:

So, by running the paster command we are passing 4 arguments: the template name (“pylons”), the project directory (“TemplateDemo”), the template_engine (by default: “mako”) and sqlalchemy (by default: False). Since it would be a waste of time to answer those questions anytime you do a rebuild (“make clean; make webapp”), these values are configureable through Sphinx’s file:

paster_template = ‘pylons’
paster_sqlalchemy = False
paster_template_engine = ‘jinja2’
paster_project_name = ‘WebAppProject

Set them once, and set them for good.

OK, the basic integration of Pylons and Sphinx is done. Now it’s time to work on Pylons webapp!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: