James Bennett wrote: > On 12/20/05, Jacob Kaplan-Moss <[EMAIL PROTECTED]> wrote: > > I'm going to aim for a revision of the way the docs work, including > > PDF versions, for around 1/1. > > Ever thought about going to something like DocBook for a downloadable > version of the documentation? You can parse that into pretty much any > output format you want, and keeps everything nice and clean in a > single source.
For this sort of project, the main drawback of using Docbook becomes annoying: it is somewhat painful to write Docbook source in a plain text editor (and I say this as somebody who is generally a big Docbook fan for many circumstances). Also, for as much documentation as Django has (which is quite a lot, really), "nice and clean in one source file" is probably a contradiction in terms (the single file would be enormous). So that isn't a real benefit (and I realise it is not compulsory for Docbook files; just pointing out that it is neither here nor there). To address the original poster's request: The Django documentation is already in restructured text format, which is very appropriate for a Python project. To create HTML or PDF from the files in the docs/ directory is not too hard at the moment. Grab the docutils package from http://docutils.sourceforge.net/index.html, unpack it and run rst2html.py any individual file in Django's docs directory. This will produce HTML output and to get it to look *exactly* like the version on www.djangoprojects.com for your local machine version, you would need to grab at least base.css from the website. I just created my own stylesheet when I did this and although my docs look a lot different, they are still eminently functional. The slight wart in this process is that all the URLs to other documentation are absolute URLs (pointing to http://www.djangoproject.com/...). Restructured text still hasn't come up with a really easy solution to the inter-document reference stuff (an area in which Docbook excels, but at the cost of some slight complexity to set up). But I solved that for my local version with a quick search and replace (well, a one-line sed-script, really) over the files before passing them to rst2html.py. This is also why it is not particularly automatic back to the contents / index page for the documentation in any individual file (without writing it in manually). That omission used to really annoy me (but then I got a grip on reality again). By the way, to produce PDF versions of the documentation (not a huge win in this case), run rst2latex.py on a file, then run latex on the result and dvi2pdf on the result of that. This gives pretty reasonable results. Not sure what Jacob has in mind for his documentation reorg, but the current stuff is still very usable from source form. Cheers, Malcolm
