You know, I'm not sure what I was thinking when I wrote that. There's no real great reason to avoid doing it other than download size, and I doubt that's a huge issue. Right now I think they're just doing releases as a .tar.gz archive of the checkout files. That'd mean an extra "build" step at release time, but that's probably trivial to automate.
That said, the source text files for the documentation are included, and whatever markup format they use (reStructuredText?) is relatively legible. HTML docs would be better, though.
> But building from source might be a pain for some people, especially newbies like me.
It's really not hard, and it's using a tool you should start using as soon as you start "serious" Python projects: Sphinx.
Building the doc from source is pretty much trivial on Unix-type systems (OSX, Linux, BSD, whatever)
* Get the django source, either tarball or source control
* Install sphinx
* Go to the root of your Django install
* `make -C docs [format...]` where format is any set of valid sphinx output formats: html, dirhtml, singlehtml, htmlhelp, qthelp, devhelp, epub, latex, latexpdf, text or man
You compiled documentation will be in the `_build/$format` directory, for each format you're building (you can build all of them). The latexpdf target requires that `pdflatex` be installed and available.
Nice! I do remember having to install a crapload of packages in order to generate PDF docs, though if one uses a lot of software with Sphinx docs, it's more than worth it, IMHO.
Would people be interested in a Downloadable HTML version as well? RTD only offers PDF for the moment, but supporting a downloadable HTML zip would be pretty simple to do as well. I note that it's the other part of the OP that isn't supported.
This is great. I was just thinking about how much more productive I am while without internet (like at a cafe without wifi), except that I can't refer to documentation easily.
If you want the django docs locally just fire up a terminal cd to the docs/ directory of your django installation then run python -m SimpleHttpServer 8880 and then visit http://localhost:8880
24 comments
[ 4.5 ms ] story [ 55.5 ms ] threadDjango uses Sphinx for its documentation system, you can just build the doc from the source tree, in whatever format you prefer.
They have to walk a careful line in that regard, and I think they made the right call on offline docs.
Flask does this[0], and so does ReadTheDocs.
It isn't clear to me what is stopping Django from providing precompiled docs, bandwidth costs?
[0] http://flask.pocoo.org/docs/
That said, the source text files for the documentation are included, and whatever markup format they use (reStructuredText?) is relatively legible. HTML docs would be better, though.
It's really not hard, and it's using a tool you should start using as soon as you start "serious" Python projects: Sphinx.
Building the doc from source is pretty much trivial on Unix-type systems (OSX, Linux, BSD, whatever)
* Get the django source, either tarball or source control
* Install sphinx
* Go to the root of your Django install
* `make -C docs [format...]` where format is any set of valid sphinx output formats: html, dirhtml, singlehtml, htmlhelp, qthelp, devhelp, epub, latex, latexpdf, text or man
You compiled documentation will be in the `_build/$format` directory, for each format you're building (you can build all of them). The latexpdf target requires that `pdflatex` be installed and available.
Good call - I just did. There's a "download" link in the sidebar now.
I can't wait for the Indian and western programming cultures to become more intertwined. I feel like we have a lot to gain from each other.
http://media.readthedocs.org/pdf/django/1.2.4/django.pdf