Mar 20 2009

Reffering to Django docs from your docs using Sphinx

Category: Django — vbmendes @ 12:25

Sphinx is a great documentation tool, and one of it’s built-in extensions is sphinx.ext.intersphinx. It simply takes your objects references for other projects and converts to links in the other project’s documentation.

In sphinx-quickstart command, it asks if you want to add this extension. If so, It adds this code to your conf.py file:

extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {'http://docs.python.org/dev': None}

As you can see, it comes integrated with python documentation by default. But what I want is to integrate with Django documentation. So I changed the code a little bit:

extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {
    'http://docs.python.org/dev': None,
    'http://docs.djangoproject.com/en/dev': 'http://docs.djangoproject.com/en/dev/_objects',
}

Sphinx looks for default for the file name objects.inv inside the documentation root, but django doesn’t provide such a file. Since ticket #10315 they provided a file like objects.inv but with a different URL: http://docs.djangoproject.com/en/dev/_objects/.

Now, all you have to do is reffer to classe or any kind of objects inside django: :class:django.contrib.auth.models.User. It will refference the User documentation inside django’s docs.

Tags: , , , ,

Mar 18 2009

Documenting Django pluggable apps with Sphinx

Category: Django — vbmendes @ 15:06

I decided to document my Django projects with the same tool used by Django team: Sphinx. It is a very good documenting tool, and was used for many other projects, including the Python Project itself.

But it has a simple problem with Django, that I found the solution rlazo’s blog. But it still has some problems, when you are trying to document a pluggable app, that doesn’t have a project, you have to configure the django settings without the project settings, since pluggable apps doesn’t have a settings module.

Thanks to apollo13, who shown me this better approach, you can simply add this code to sphinx’s conf.py file:

from django.conf import settings
settings.configure()

With this approach, you don’t need to add any kind of fake files in your project.

Tags: , , , ,

Feb 01 2009

MEDIA_URL and context from processors available in HTTP 500 template

Category: Django — vbmendes @ 22:43

It’s easy to create a custom template for HTTP 500 errors. All you have to do is create a file named 500.html in any of the application’s TEMPLATE_DIRS. But in almost all cases you want to use media in this page. It’s good to have an error page with the same look and feel of the system itself.

The default HTTP 500 handler in django uses Context instead of RequestContext. It means that none of your template context processors will be loaded, and the MEDIA_URL variable available in the template system comes exactly from one of these processors. So, without template context processors, we get no MEDIA_URL variable in templates.

Searching in google for a solution to this problem I found a snippet[1] that solves the MEDIA_URL problem. But it still doesn’t load the processors, all it does is pass the MEDIA_URL variable to the context for template. So I decided to make simple changes in it to load the processors. And here is the complete code:

def server_error(request, template_name='500.html'):
    from django.template import RequestContext
    from django.http import HttpResponseServerError
    t = loader.get_template(template_name)
    return HttpResponseServerError(t.render(RequestContext(request)))

Put this code in any views file you want and then define it as the handler500 in your urls.py:

handler500 = 'views.server_error'

[1] http://www.djangosnippets.org/snippets/1199/

As Felipe Prenholato mentioned in comments, if you use this code and one of your template context processors raises an Exception it will break badly and will show an ungly HTTP 500 page from your http server.

Tags: , , ,

Jan 29 2009

Django ORM now supports fields references in filters

Category: Django — vbmendes @ 08:28

Today was added a new feature to django ORM. Now it supports references to fields in filters expressions. Just checkout the SVN version and enjoy it.

Before this update, queryset could be filtered only by absolute values.

queryset.filter(field='absolute value')

Will generate somthing like this:

SELECT * FROM table_name WHERE field = 'absolute value';

Now you can filter by another’s table field value.

queryset.filter(field=F('another_field'))

Will generate something like this:

SELECT * FROM table_name WHERE field = another_field;

The feature also supports arithmetical operations in the lookups so you can do filters where the views_number is twice as big as the comments_number.

queryset.filter(views_number__gt=F('comments_number')*2)

Will generate a SQL like this:

SELECT * FROM table_name WHERE views_number = comments_number*2;

It’s a very good feature. So, checkout the SVN version and take a look at docs/topics/db/queries.txt to know more about this.

Tags: , ,

Jan 19 2009

External apps i18n in Django

Category: Django — vbmendes @ 12:59

Django has the good feature of internationalization. It’s very simple to use that it generates the .po files automatically from your project. All you have to do is complete the .po file with the translated text. To create these files, all you have to do is create a folder in your project called locale and run the command ./manage.py makemessages -l <your-locale>. That’s very easy, but I realized that it don’t get the string inside your external apps. So, after some search in internet, i found a way to get this file with the app’s strings. And, as all in django must be, it is a pluggable way to solve the problem.

All you have to do is create a folder named locale inside your app’s folder and run the command django-admin.py makemessages -l <your-locale> and it will create the file for you. To compile the messages, use the command django-admin.py compilemessages -l <your-locale>

That’s it, as simple as everything in django.

Tags: , , ,

Jan 15 2009

Django Aggregation Released

Category: Django,Python — vbmendes @ 11:57

The aggregation is already available in Django SVN version. Now, it’s possible to do things such count authors of all book entries, count comments os all post entries, sum values of all sales to a client and much more.

Here is the official documentation of this feature: http://docs.djangoproject.com/en/dev/topics/db/aggregation/

Tags: , ,

« Previous Page — Next Page »