Ubuntu API Website
For much of the past year I’ve been working on the Ubuntu API Website, a Django project for hosting all of the API documentation for the Ubuntu SDK, covering a variety of languages, toolkits and libraries. It’s been a lot of work for just one person, to make it really awesome I’m going to need help from you guys and gals in the community.
To help smooth the onramp to getting started, here is a breakdown of the different components in the site and how they all fit together. You should grab a copy of the branch from Launchpad so you can follow along by running: bzr branch lp:ubuntu-api-website
Django
First off, let’s talk about the framework. The API website uses Django, a very popular Python webapp framework that’s also used by other community-run Ubuntu websites, such as Summit and the LoCo Team Portal, which makes it a good fit. A Django project consists of one or more Django “apps”, which I will cover below. Each app consists of “models”, which use the Django ORM (Object-Relational Mapping) to handle all of the database interactions for us, so we can stick to just Python and not worry about SQL. Apps also have “views”, which are classes or functions that are called when a URL is requested. Finally, Django provides a default templating engine that views can use to produce HTML.
If you’re not familiar with Django already, you should take the online Tutorial. It only takes about an hour to go through it all, and by the end you’ll have learned all of the fundamental things about building a Django site.
Branch Root
When you first get the branch you’ll see one folder and a handful of files. The folder, developer_network, is the Django project root, inside there is all of the source code for the website. Most of your time is going to be spent in there.
Also in the branch root you’ll find some files that are used for managing the project itself. Most important of these is the README file, which gives step by step instructions for getting it running on your machine. You will want to follow these instructions before you start changing code. Among the instructions is using the requirements.txt file, also in the branch root, to setup a virtualenv environment. Virtualenv lets you create a Python runtime specifically for this project, without it conflicting with your system-wide Python installation.
The other files you can ignore for now, they’re used for packaging and deploying the site, you won’t need them during development.
./developer_network/
As I mentioned above, this folder is the Django project root. It has sub-folders for each of the Django apps used by this project. I will go into more detail on each of these apps below.
This folder also contains three important files for Django: manage.py, urls.py and settings.py
manage.py is used for a number of commands you can give to Django. In the README you’ll have seen it used to call syncdb, migrate and initdb. These create the database tables, apply any table schema changes, and load them with initial data. These commands only need to be run once. It also has you run collectstatic and runserver. The first collects static files (images, css, javascript, etc) from all of the apps and puts them all into a single ./static/ folder in the project root, you’ll need to run that whenever you change one of those files in an app. The second, runserver, runs a local HTTP server for your app, this is very handy during development when you don’t want to be bothered with a full Apache server. You can run this anytime you want to see your site “live”.
settings.py contains all of the Django configuration for the project. There’s too much to go into detail on here, and you’ll rarely need to touch it anyway.
urls.py is the file that maps URLs to an application’s views, it’s basically a list of regular-expressions that try to match the requested URL, and a python function or class to call for that match. If you took the Django project tutorial I recommended above, you should have a pretty good understanding of what it does. If you ever add a new view, you’ll need to add a corresponding line to this file in order for Django to know about it. If you want to know what view handles a given URL, you can just look it up here.
./developer_network/ubuntu_website/
If you followed the README in the branch root, the first thing it has you do is grab another bzr branch and put it in ./developer_network/ubuntu_website. This is a Django app that does nothing more than provide a base template for all of your project’s pages. It’s generic enough to be used by other Django-powered websites, so it’s kept in a separate branch that each one can pull from. It’s rare that you’ll need to make changes in here, but if you do just remember that you need to push you changes branch to the ubuntu-community-webthemes project on Launchpad.
./developer_network/rest_framework/
This is a 3rd party Django app that provides the RESTful JSON API for the site. You should not make changes to this app, since that would put us out of sync with the upstream code, and would make it difficult to pull in updates from them in the future. All of the code specific to the Ubuntu API Website’s services are in the developer_network/service/ app.
./developer_network/search/
This app isn’t being used yet, but it is intended for giving better search functionality to the site. There are some models here already, but nothing that is being used. So if searching is your thing, this is the app you’ll want to work in.
./developer_network/related/
This is another app that isn’t being used yet, but is intended to allow users to link additional content to the API documentation. This is one of the major goals of the site, and a relatively easy area to get started contributing. There are already models defined for code snippets, Images and links. Snippets and Links should be relatively straightforward to implement. Images will be a little harder, because the site runs on multiple instances in the cloud, and each instance will need access to the image, so we can’t just use the Django default of saving them to local files. This is the best place for you to make an impact on the site.
./developer_network/common/
The common app provides views for logging in and out of the app, as well as views for handling 404 and 500 errors when the arise. It also provides some base models the site’s page hierarchy. This starts with a Topic at the top, which would be qml or html5 in our site, followed by a Version which lets us host different sets of docs for the different supported releases of Ubuntu. Finally each set of docs is placed within a Section, such as Graphical Interface or Platform Service to help the user browse them based on use.
./developer_network/apidocs/
This app provides models that correspond directly to pieces of documentation that are being imported. Documentation can be imported either as an Element that represents a specific part of the API, such as a class or function, or as a Page that represents long-form text on how to use the Elements themselves. Each one of these may also have a given Namespace attached to it, if the imported language supports it, to further categorize them.
./developer_network/web/
Finally we get into the app that is actually generates the pages. This app has no models, but uses the ones defined in the common and apidocs apps. This app defines all of the views and templates used by the website’s pages, so no matter what you are working on there’s a good chance you’ll need to make changes in here too. The templates defined here use the ones in ubuntu_website as a base, and then add site and page specific markup for each.
Getting Started
If you’re still reading this far down, congratulations! You have all the information you need to dive in and start turning a boring but functional website into a dynamic, collaborative information hub for Ubuntu app developers. But you don’t need to go it alone, I’m on IRC all the time, so come find me (mhall119) in #ubuntu-website or #ubuntu-app-devel on Freenode and let me know where you want to start. If you don’t do IRC, leave a comment below and I’ll respond to it. And of course you can find the project, file bugs (or pick bugs to fix) and get the code all from the Launchpad project.