# django-bakery

A set of helpers for baking your Django site out as flat files

## Why and what for

The code documented here is intended to make it easier to save every page generated by a database-backed site as a flat file. This allows you to host the site using a static-file service like [Amazon S3](http://en.wikipedia.org/wiki/Amazon_S3).

We call this process “baking.” It’s our path to cheap, stable hosting for simple sites. We've used it for publishing [election results](http://graphics.latimes.com/2012-election-gop-results-map-iowa/), [timelines](http://timelines.latimes.com/complete-guide-lafd-hiring-controversy/), [documents](http://documents.latimes.com/barack-obama-long-form-birth-certificate/), [interactive tables](http://spreadsheets.latimes.com/city-appointees-tied-garcetti/), [special projects](http://graphics.latimes.com/flight-from-rage/) and [numerous](http://graphics.latimes.com/towergraphic-washington-landslide-victims/) [other](http://graphics.latimes.com/how-fast-is-lafd/) [things](http://graphics.latimes.com/picksheet-critics-picks-april-4-10-2014/).

The system comes with some major advantages, like:

1. No database crashes
2. Zero server configuration and upkeep
3. No need to optimize your app code
4. You don’t pay to host CPUs, only bandwidth
5. An offline administration panel is more secure
6. Less stress (This one can change your life)

There are drawbacks. For one, you have to integrate the "bakery" into your code base. More important, a flat site can only be so complex. No online database means your site is all read and no write, which means no user-generated content and no complex searches.

[Django's class-based views](https://docs.djangoproject.com/en/dev/topics/class-based-views/) are at the heart of our approach. Putting all the pieces together is a little tricky at first, particularly if you haven't studied [the Django source code](https://github.com/django/django/tree/master/django/views/generic) or lack experience [working with Python classes](http://www.diveintopython.net/object_oriented_framework/defining_classes.html) in general. But once you figure it out, you can do all kinds of crazy things: Like configuring Django to bake out your entire site with a single command.

Here's how.

## Documentation

```{toctree}
:maxdepth: 1

gettingstarted
commonchallenges
buildableviews
buildablemodels
buildablefeeds
settingsvariables
managementcommands
credits
```

## In the wild

- Hundreds of Los Angeles Times custom pages at [latimes.com/projects](http://www.latimes.com/projects/) and [graphics.latimes.com](http://graphics.latimes.com/)
- The California Civic Data Coalition's [data downloads](https://calaccess.californiacivicdata.org/downloads/latest/)
- [A](https://apps.statesman.com/votetracker/entities/austin-city-council/) [series](https://apps.statesman.com/sxsw/2017/) [of](https://apps.statesman.com/question-of-restraint/data/) [projects](https://apps.statesman.com/homicides/) [by](https://apps.statesman.com/council-candidate-explorer/election/2016/) [the](https://apps.statesman.com/austin360/eats/) [Austin American Statesman](https://apps.statesman.com/austin360/booze-guide/)
- The Dallas Morning News' [legislative tracker](http://interactives.dallasnews.com/2017/the-85th/)
- Newsday's [police misconduct investigation](http://data.newsday.com/crime/police-misconduct/)
- Southern California Public Radio's [water report tracker](http://projects.scpr.org/applications/monthly-water-use/)
- The Daily Californian's [sexual misconduct case tracker](http://projects.dailycal.org/misconduct/)
- The [pretalx](https://pretalx.org) open-source conference management system
- The [static-site extension](https://github.com/moorinteractive/wagtail-bakery) to the Wagtail content management system

Have you used django bakery for something cool? Send a link to [b@palewi.re](mailto:b@palewi.re) and we will add it to this list.

## Considering alternatives

If you are seeking to "bake" out a very simple site, maybe you don't have a database or only a single page, it is quicker
to try [Tarbell](https://github.com/tarbell-project/tarbell) or [Frozen-Flask](https://pythonhosted.org/Frozen-Flask/), which don't require all
the overhead of a full Django installation.

This library is better suited for projects that require a database, want to take advantage of other Django features (like the administration panel)
or require more complex views.

## Contributing

- Code repository: [https://github.com/palewire/django-bakery/](https://github.com/palewire/django-bakery/)
- Issues: [https://github.com/palewire/django-bakery/issues](https://github.com/palewire/django-bakery/issues)
- Packaging: [https://pypi.python.org/pypi/django-bakery](https://pypi.python.org/pypi/django-bakery)