Django Offline Docs | Hacker News Reader

Django Offline Docs

sramana.in

118 pointssenko22 comments

Thanks everyone. I created this page long back, but later ReadtheDocs.org started offering PDF downloads of docs, making it redundant. Django is available at http://media.readthedocs.org/pdf/django/latest/django.pdf

Also see http://readthedocs.org/projects/django/ for a couple of other formats: ePub and manpage (that's a long manpage...)

Thank you! I appreciated the thoughtful "Why?" column as much as the offline docs themselves.

Thanks sramana!

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.

1.2.4 and all the other versions that are built are also available. They aren't linked from the site, but are get-able with a little URL munging:

http://media.readthedocs.org/pdf/django/1.2.4/django.pdf

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.

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

I've always used (Sphinx and other deps required):

  git clone git://github.com/django/django && cd django/docs && make html

The Python docs can similarly be built for offline reading.

There are also some other sphinx templates that look a bit better than what Django ships with, IMO.

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.

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.

Wow! Good job. I think Django should make this official. I like reading PDF but I believe ePub seems better for portable reading devices.

> I think Django should make this official.

Django uses Sphinx for its documentation system, you can just build the doc from the source tree, in whatever format you prefer.

It's true. But building from source might be a pain for some people, especially newbies like me.

If Django makes too many things official, installing it will become a pain for some people, especially newbies.

They have to walk a careful line in that regard, and I think they made the right call on offline docs.

I don't get it, what does providing a pdf or zipped html files have to do with installing?

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/

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.

> I think Django should make this official.

Good call - I just did. There's a "download" link in the sidebar now.

Django Docs are already available offline (for those who look)

Very nice job, this will be very helpful . Congrats.

As u said, when there is less connectivity it really makes sense.

Reply on news.ycombinator.com