Living on the Edge

Django Docs Refactor

Posted on August 23, 2008

Django documentation has been refactored (Changeset 8506) using the excellent Sphinx – Python documentation generator. This is the same package used to generate the new Python documentation Check out the new docs at http://docs.djangoproject.com/. Now I have to go and update all my shortcut snippets. Thanks go especially to Jacob Kaplan-Moss and numerous contributors for all of their hard work on this one.

Filed under: Django | Tagged with: doc pocoo python refactor sphinx  |

Comments
  1. Doug Napoleone – August 23, 2008 @ 09:57 PM

    Going to take me some time to get used to it. There is a lot to love with the new documentation, but I am having a hard time finding things. The problem is that I am used to the old docs and I know where everything is in them and can just go to the exact page in under 4 clicks.

    The new docs (at least the title page) is too spread out. I find I have to do quite a bit of scrolling to find things. That is a minor CSS gripe.

    At the end of the day, it will just take me time to find where things are now. Like sitting down at a computer with a dvorak keyboard for the first time. Once I get use to the new layout I am sure I will be more productive than with the old docs.

    Fantastic job everyone!

  2. Pascal – August 24, 2008 @ 05:36 AM

    Very cool! Like Doug said, it will take some time to get used to the new organisation, but I’m sure it will be more effective than the old system.

    One thing I still really miss is a search for the documentation. Afaik Sphinx offers a Javascript/JSON based search engine, so why not use it?

  3. Empty – August 24, 2008 @ 12:44 PM

    Pascal: Jacob mentioned in #django-dev that he has to make some tweaks before he can turn on the search.

    Doug: Yeah I’m excited about the new docs but it’s going to take a while to find things quickly like I can do now.

  4. Yeago – August 25, 2008 @ 03:35 AM

    Highly disliking the separation of sensible topics into upwards of 6 discrete pages. Makes searching via CTRL+F less effective.