SmileyChris

Django documentation

Rambling on about Django 90 months ago.

There have been several times when I couldn't connect to the Internet and needed to view the official Django documentation and so had to fall back to the text versions. Even when I have been connected, I always thought it'd be better if you could just access the documentation (as HTML) locally.

So here's an application I wrote which provides access to the official Django documentation as HTML inside of your local Django administration documentation.

After installation, a new documentation area titled "Django Documentation" will appear inside of the Documentation section of your Django administration section.

Read the readme or see what it looks like.

Update v1.1: Small update, changed it so that if the matching .txt file can not be found, it 404s. Better than an OSError :P

Update v1.2: Changing the location where the HTML compiled docs are written to (now inside MEDIA_URL) and fix an outstanding issue with some pages failing.

Recent auto-escape changes to trunk: If you're using this with the recent changes to trunk, you'll need to make a small change to templates/admin_doc/django/doc.html. Add |safe to {{ doc.toc }} and {{ doc.html_body }}. At least until I get another version done :P

Final update (2007-02-21): I got around to making it a Google code project: http://code.google.com/p/django-docs/ (I've taken down the links from here to the old versions - use the SVN now)

Leave a comment or see my other ramblings.

Comments (22)

whiteinge said: (90 months ago)

Excellent! Much faster than hitting the official website all the time. Thanks!

tom said: (89 months ago)

thanks, brilliant....

Richard said: (89 months ago)

Extremely useful. This saves me spidering the django site for the documentation for off-line reference.

Richard said: (89 months ago)

Chris, I am running with the latest SVN django code. Have you experienced some of the django documentation breaking the rest rendering? Check out the "Sending email" page under the heading Solving Specific Problems on the documentation index page. Your code is not the cause and there are several pages affected. django\contrib\admin\utils.py baulks at `EmailMessage` on line 229 of the email.txt file. the django code doesn't seem to translate the backquotes to <cite>. Can you confirm this behaviour?

Richard said: (89 months ago)

Chris, sorry after further testing, I think the problem is in your code. Removing django-docs from my project enables django to render backquoted words correctly with <cite>.

Richard said: (89 months ago)

While trying to trace the error, it has started working fine. I can't identify what has changed to make it work.
Anyway, great tool.

:) SmileyChris said: (89 months ago)

Hi Richard,

No I have never encountered that. And you can see it's working fine here: http://smileychris.tactful.co.nz/admin/doc/django/

amit upadhyay said: (88 months ago)

Very cool man! Love it.

Jason Davies said: (88 months ago)

Lovely! Very pleasing to use...

dall said: (87 months ago)

hi, I get Page not found (404), when access some link from doc/django/ i'm using svn of django and docutils!

:) Chris said: (87 months ago)

Hi Dall. Some of the documentation links are out of date in the django documentation - www.djangoproject.com uses some funky redirects. If you find these out of date links, open a ticket here: http://code.djangoproject.com/simpleticket so it can be fixed.

Ricardo Fuentes said: (84 months ago)

oh guy, you save my day! :D

Pete Crosier said: (83 months ago)

Thanks Chris, this will come in handy later on today ;D

Damon Kiesow said: (83 months ago)

Chris -

I am seeing the same error on my site and in your example site. All of the docs appear with the HTML encoded.

<ul class='toc'><li><p class="first"><a class="reference" href="#creating-a-project" id="id3">Creating a project</a></p> <ul class="simple"> <li><a class="reference"

Any thoughts?

:) Chris said: (83 months ago)

Hi Damon,

I've had a couple of people contact me about this. I haven't updated the project to accommodate for the changes to trunk regarding auto-escaping.

Just now I have added a comment to this post to alert others, the fix is easy enough.

I really should get around to making this into a proper django code project. If anyone wants to assist with this, get in touch :)

Damon Kiesow said: (83 months ago)

Chris - I figured 'escaping' was the problem - but was not sure the fix. Your suggestion worked perfectly.

thanks

Damon

cyxapeff said: (83 months ago)

Thanks! It's very good.

sohrab said: (81 months ago)

Thank you! why don't you go and fix that small problem? any way, again, thanks.

Tane Piper said: (79 months ago)

Very nice little app, I've decided to include it in the development version of my app so I don't have to keep referring to the online docs.

Shihan said: (75 months ago)

Hi,

The docs in django trunk is also not complete in all case, just think about the model examples in djangoproject.com, its not at trunk. So, what I am doing to get the offline version is preiodically downloading the django doc site using a simple project for httrack. I have also a winchm project setup to convert the downloaded site into chm format. Here's the download link for CHM version (sorry for link to free files haring host)

http://www.icefile.info/index.php?page=main&id=...

Also you are currently hard coding the index page template which become outdated soon if you don't update the template file as well. It would be better if you'd update the django docs app to use sphinx library to generate the documentation on the fly which is done in django doc site.

Regards,
Shihan

EmacsFiend said: (73 months ago)

Excellent! Anyone know the best was to get it to work with Emacs documentation at point Help View ElDoc

Pavan Mishra said: (72 months ago)

Very usefull, thanks.

Leave a comment