Django documentation (for 1.0). The documentation refactor is in: the docs for the upcoming 1.0 release have been tidied up, rearranged and ported to a new documentation system based on Sphinx (the Python documentation toolkit, NOT the full-text search engine). The URL has also changed to docs.djangoproject.com.
Sign in with 
OpenID
It's not clear to me that the new organisation is better than the old organisation. There seem to be many different paths through the new structure, and it's not obvious what is tutorial and what is reference, or where to find the definitive reference sections. Perhaps it was just familiarity, but I found the old organisation clearer.
Could you explain the rationale for the new structure and provide advice on how best to use it?
Thanks.
Rodney Topor - 24th August 2008 13:43 - #
Does browsing http://docs.djangoproject.com/en/dev/contents/ help at all?
Yes I agree that's the best starting point. I expect I and others will get used to it quickly enough.
Can I request a search box on every page, as with the old /documentation/ page?
As a random example, if I want to learn about "permalink", I can no longer find it in the index or by searching.
Also, eventually, the Django home page needs to be updated to link to the new documentation.
Rodney Topor - 24th August 2008 22:47 - #
I've recently taken a great interest in Sphinx. When you say that their system is "based on Sphinx," do you mean they are using Sphinx or have modified/enhanced Sphinx and are using that? If the latter, do you know where I can find what they've changed?
PS--I tried using yahoo.com's beta OpenID support to post my message, but when I hit "Sign In", I got a 404 error. Any thoughts?
Shawn Wheatley - 25th August 2008 19:29 - #
I'd also love to read more about how Sphinx fits into the picture.
Is the documentation system itself open source?
It's all open source - you can see how it all works by browsing through the directories that start with an underscore here:
http://code.djangoproject.com/browser/django/trunk /docs
The http://docs.djangoproject.com/ site itself is also available in public SVN:
http://code.djangoproject.com/browser/djangoprojec t.com/djangodocs
If you are using a full text search engine, shouldn't you have a search box? I'm at a loss for where it might be.
If there is none, might I request at least a little google search box like the old docs has?
In this context Sphinx is the Python documentation toolkit - NOT the full-text search engine. Here's the Sphinx Django is using: http://sphinx.pocoo.org/. I've clarified that in the post now.
Ah - that makes more sense :)
Btw. I saw that you are monkey patching the pickle builder. A cleaner and more reusable solution would be subclassing it, giving it a new name and registering :-)
Armin Ronacher - 29th August 2008 12:04 - #